xref: /linux-4.4.14/Documentation/DocBook/device-drivers.aux.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<book id="LinuxDriversAPI">
 <bookinfo>
  <title>Linux Device Drivers</title>

  <legalnotice>
   <para>
     This documentation is free software; you can redistribute
     it and/or modify it under the terms of the GNU General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later
     version.
   </para>

   <para>
     This program is distributed in the hope that it will be
     useful, but WITHOUT ANY WARRANTY; without even the implied
     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
     See the GNU General Public License for more details.
   </para>

   <para>
     You should have received a copy of the GNU General Public
     License along with this program; if not, write to the Free
     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
     MA 02111-1307 USA
   </para>

   <para>
     For more details see the file COPYING in the source
     distribution of Linux.
   </para>
  </legalnotice>
 </bookinfo>

<toc></toc>

  <chapter id="Basics">
     <title>Driver Basics</title>
     <sect1><title>Driver Entry and Exit points</title>
<!-- include/linux/init.h -->
<refentry>
 <refnamediv>
  <refname>
   include/linux/init.h
  </refname>
  <refpurpose>
   Document generation inconsistency
  </refpurpose>
 </refnamediv>
 <refsect1>
  <title>
   Oops
  </title>
  <warning>
   <para>
    The template for this document tried to insert
    the structured comment from the file
    <filename>include/linux/init.h</filename> at this point,
    but none was found.
    This dummy section is inserted to allow
    generation to continue.
   </para>
  </warning>
 </refsect1>
</refentry>
     </sect1>

     <sect1><title>Atomic and pointer manipulation</title>
<!-- arch/x86/include/asm/atomic.h -->
<refentry id="API-atomic-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_read</refname>
 <refpurpose>
  read atomic variable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>atomic_read </function></funcdef>
   <paramdef>const atomic_t * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically reads the value of <parameter>v</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-set">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_set</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_set</refname>
 <refpurpose>
     set atomic variable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>atomic_set </function></funcdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
   <paramdef>int <parameter>i</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     required value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically sets the value of <parameter>v</parameter> to <parameter>i</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_add</refname>
 <refpurpose>
     add integer to atomic variable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>atomic_add </function></funcdef>
   <paramdef>int <parameter>i</parameter></paramdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     integer value to add
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically adds <parameter>i</parameter> to <parameter>v</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-sub">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_sub</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_sub</refname>
 <refpurpose>
     subtract integer from atomic variable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>atomic_sub </function></funcdef>
   <paramdef>int <parameter>i</parameter></paramdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     integer value to subtract
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically subtracts <parameter>i</parameter> from <parameter>v</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-sub-and-test">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_sub_and_test</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_sub_and_test</refname>
 <refpurpose>
     subtract value from variable and test result
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>atomic_sub_and_test </function></funcdef>
   <paramdef>int <parameter>i</parameter></paramdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     integer value to subtract
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically subtracts <parameter>i</parameter> from <parameter>v</parameter> and returns
   true if the result is zero, or false for all
   other cases.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-inc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_inc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_inc</refname>
 <refpurpose>
     increment atomic variable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>atomic_inc </function></funcdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically increments <parameter>v</parameter> by 1.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-dec">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_dec</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_dec</refname>
 <refpurpose>
     decrement atomic variable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>atomic_dec </function></funcdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically decrements <parameter>v</parameter> by 1.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-dec-and-test">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_dec_and_test</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_dec_and_test</refname>
 <refpurpose>
     decrement and test
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>atomic_dec_and_test </function></funcdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically decrements <parameter>v</parameter> by 1 and
   returns true if the result is 0, or false for all other
   cases.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-inc-and-test">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_inc_and_test</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_inc_and_test</refname>
 <refpurpose>
     increment and test
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>atomic_inc_and_test </function></funcdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically increments <parameter>v</parameter> by 1
   and returns true if the result is zero, or false for all
   other cases.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-add-negative">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_add_negative</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_add_negative</refname>
 <refpurpose>
     add and test if negative
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>atomic_add_negative </function></funcdef>
   <paramdef>int <parameter>i</parameter></paramdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     integer value to add
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically adds <parameter>i</parameter> to <parameter>v</parameter> and returns true
   if the result is negative, or false when
   result is greater than or equal to zero.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-add-return">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_add_return</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_add_return</refname>
 <refpurpose>
     add integer and return
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>atomic_add_return </function></funcdef>
   <paramdef>int <parameter>i</parameter></paramdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     integer value to add
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically adds <parameter>i</parameter> to <parameter>v</parameter> and returns <parameter>i</parameter> + <parameter>v</parameter>
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-sub-return">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_sub_return</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_sub_return</refname>
 <refpurpose>
     subtract integer and return
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>atomic_sub_return </function></funcdef>
   <paramdef>int <parameter>i</parameter></paramdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     integer value to subtract
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically subtracts <parameter>i</parameter> from <parameter>v</parameter> and returns <parameter>v</parameter> - <parameter>i</parameter>
</para>
</refsect1>
</refentry>

<refentry id="API---atomic-add-unless">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__atomic_add_unless</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__atomic_add_unless</refname>
 <refpurpose>
     add unless the number is already a given value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__atomic_add_unless </function></funcdef>
   <paramdef>atomic_t * <parameter>v</parameter></paramdef>
   <paramdef>int <parameter>a</parameter></paramdef>
   <paramdef>int <parameter>u</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer of type atomic_t
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>a</parameter></term>
   <listitem>
    <para>
     the amount to add to v...
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>u</parameter></term>
   <listitem>
    <para>
     ...unless v is equal to u.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically adds <parameter>a</parameter> to <parameter>v</parameter>, so long as <parameter>v</parameter> was not already <parameter>u</parameter>.
   Returns the old value of <parameter>v</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-inc-short">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_inc_short</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_inc_short</refname>
 <refpurpose>
     increment of a short integer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>short int <function>atomic_inc_short </function></funcdef>
   <paramdef>short int * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     pointer to type int
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Atomically adds 1 to <parameter>v</parameter>
   Returns the new value of <parameter>u</parameter>
</para>
</refsect1>
</refentry>

     </sect1>

     <sect1><title>Delaying, scheduling, and timer routines</title>
<!-- include/linux/sched.h -->
<refentry id="API-struct-prev-cputime">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct prev_cputime</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct prev_cputime</refname>
 <refpurpose>
  snaphsot of system and user cputime
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct prev_cputime {
#ifndef CONFIG_VIRT_CPU_ACCOUNTING_NATIVE
  cputime_t utime;
  cputime_t stime;
  raw_spinlock_t lock;
#endif
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>utime</term>
      <listitem><para>
time spent in user mode
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>stime</term>
      <listitem><para>
time spent in system mode
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
protects the above two fields
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Stores previous user/system time values such that we can guarantee
   monotonicity.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-task-cputime">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct task_cputime</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct task_cputime</refname>
 <refpurpose>
     collected CPU time counts
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct task_cputime {
  cputime_t utime;
  cputime_t stime;
  unsigned long long sum_exec_runtime;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>utime</term>
      <listitem><para>
   time spent in user mode, in <structname>cputime_t</structname> units
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>stime</term>
      <listitem><para>
   time spent in kernel mode, in <structname>cputime_t</structname> units
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sum_exec_runtime</term>
      <listitem><para>
   total time spent on the CPU, in nanoseconds
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This structure groups together three kinds of CPU time that are tracked for
   threads and thread groups.  Most things considering CPU time want to group
   these counts together and treat all three of them in parallel.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-thread-group-cputimer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct thread_group_cputimer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct thread_group_cputimer</refname>
 <refpurpose>
     thread group interval timer counts
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct thread_group_cputimer {
  struct task_cputime_atomic cputime_atomic;
  bool running;
  bool checking_timer;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>cputime_atomic</term>
      <listitem><para>
   atomic thread group interval timers.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>running</term>
      <listitem><para>
   true when there are timers running and
   <parameter>cputime_atomic</parameter> receives updates.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>checking_timer</term>
      <listitem><para>
   true when a thread in the group is in the
   process of checking for thread group timers.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This structure contains the version of task_cputime, above, that is
   used for thread group CPU timer calculations.
</para>
</refsect1>
</refentry>

<refentry id="API-pid-alive">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pid_alive</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pid_alive</refname>
 <refpurpose>
     check that a task structure is not stale
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pid_alive </function></funcdef>
   <paramdef>const struct task_struct * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     Task structure to be checked.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Test if a process is not yet dead (at most zombie state)
   If pid_alive fails, then pointers within the task structure
   can be stale and must not be dereferenced.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 if the process is alive. 0 otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-is-global-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>is_global_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>is_global_init</refname>
 <refpurpose>
     check if a task structure is init. Since init is free to have sub-threads we need to check tgid.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>is_global_init </function></funcdef>
   <paramdef>struct task_struct * <parameter>tsk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>tsk</parameter></term>
   <listitem>
    <para>
     Task structure to be checked.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check if a task structure is the first user space task the kernel created.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 if the task structure is init. 0 otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-task-nice">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>task_nice</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>task_nice</refname>
 <refpurpose>
     return the nice value of a given task.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>task_nice </function></funcdef>
   <paramdef>const struct task_struct * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     the task in question.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The nice value [ -20 ... 0 ... 19 ].
</para>
</refsect1>
</refentry>

<refentry id="API-is-idle-task">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>is_idle_task</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>is_idle_task</refname>
 <refpurpose>
     is the specified task an idle task?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>is_idle_task </function></funcdef>
   <paramdef>const struct task_struct * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     the task in question.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 if <parameter>p</parameter> is an idle task. 0 otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-threadgroup-change-begin">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>threadgroup_change_begin</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>threadgroup_change_begin</refname>
 <refpurpose>
     mark the beginning of changes to a threadgroup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>threadgroup_change_begin </function></funcdef>
   <paramdef>struct task_struct * <parameter>tsk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>tsk</parameter></term>
   <listitem>
    <para>
     task causing the changes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   All operations which modify a threadgroup - a new thread joining the
   group, death of a member thread (the assertion of PF_EXITING) and
   exec(2) dethreading the process and replacing the leader - are wrapped
   by threadgroup_change_{begin|end}().  This is to provide a place which
   subsystems needing threadgroup stability can hook into for
   synchronization.
</para>
</refsect1>
</refentry>

<refentry id="API-threadgroup-change-end">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>threadgroup_change_end</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>threadgroup_change_end</refname>
 <refpurpose>
     mark the end of changes to a threadgroup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>threadgroup_change_end </function></funcdef>
   <paramdef>struct task_struct * <parameter>tsk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>tsk</parameter></term>
   <listitem>
    <para>
     task causing the changes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   See <function><link linkend="API-threadgroup-change-begin">threadgroup_change_begin</link></function>.
</para>
</refsect1>
</refentry>

<!-- kernel/sched/core.c -->
<refentry id="API-wake-up-process">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wake_up_process</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wake_up_process</refname>
 <refpurpose>
  Wake up a specific process
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>wake_up_process </function></funcdef>
   <paramdef>struct task_struct * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     The process to be woken up.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Attempt to wake up the nominated process and move it to the set of runnable
   processes.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 if the process was woken up, 0 if it was already running.
   </para><para>

   It may be assumed that this function implies a write memory barrier before
   changing the task state if and only if any tasks are woken up.
</para>
</refsect1>
</refentry>

<refentry id="API-preempt-notifier-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>preempt_notifier_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>preempt_notifier_register</refname>
 <refpurpose>
     tell me when current is being preempted &amp; rescheduled
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>preempt_notifier_register </function></funcdef>
   <paramdef>struct preempt_notifier * <parameter>notifier</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>notifier</parameter></term>
   <listitem>
    <para>
     notifier struct to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-preempt-notifier-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>preempt_notifier_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>preempt_notifier_unregister</refname>
 <refpurpose>
     no longer interested in preemption notifications
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>preempt_notifier_unregister </function></funcdef>
   <paramdef>struct preempt_notifier * <parameter>notifier</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>notifier</parameter></term>
   <listitem>
    <para>
     notifier struct to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is *not* safe to call from within a preemption notifier.
</para>
</refsect1>
</refentry>

<refentry id="API-preempt-schedule-notrace">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>preempt_schedule_notrace</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>preempt_schedule_notrace</refname>
 <refpurpose>
     preempt_schedule called by tracing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__visible void __sched notrace <function>preempt_schedule_notrace </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   The tracing infrastructure uses preempt_enable_notrace to prevent
   recursion and tracing preempt enabling caused by the tracing
   infrastructure itself. But as tracing can happen in areas coming
   from userspace or just about to enter userspace, a preempt enable
   can occur before <function>user_exit</function> is called. This will cause the scheduler
   to be called when the system is still in usermode.
   </para><para>

   To prevent this, the preempt_enable_notrace will use this function
   instead of <function>preempt_schedule</function> to exit user context if needed before
   calling the scheduler.
</para>
</refsect1>
</refentry>

<refentry id="API-sched-setscheduler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sched_setscheduler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sched_setscheduler</refname>
 <refpurpose>
     change the scheduling policy and/or RT priority of a thread.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sched_setscheduler </function></funcdef>
   <paramdef>struct task_struct * <parameter>p</parameter></paramdef>
   <paramdef>int <parameter>policy</parameter></paramdef>
   <paramdef>const struct sched_param * <parameter>param</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     the task in question.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>policy</parameter></term>
   <listitem>
    <para>
     new policy.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>param</parameter></term>
   <listitem>
    <para>
     structure containing the new RT priority.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success. An error code otherwise.
   </para><para>

   NOTE that the task may be already dead.
</para>
</refsect1>
</refentry>

<refentry id="API-sched-setscheduler-nocheck">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sched_setscheduler_nocheck</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sched_setscheduler_nocheck</refname>
 <refpurpose>
     change the scheduling policy and/or RT priority of a thread from kernelspace.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sched_setscheduler_nocheck </function></funcdef>
   <paramdef>struct task_struct * <parameter>p</parameter></paramdef>
   <paramdef>int <parameter>policy</parameter></paramdef>
   <paramdef>const struct sched_param * <parameter>param</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     the task in question.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>policy</parameter></term>
   <listitem>
    <para>
     new policy.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>param</parameter></term>
   <listitem>
    <para>
     structure containing the new RT priority.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Just like sched_setscheduler, only don't bother checking if the
   current context has permission.  For example, this is needed in
   <function>stop_machine</function>: we create temporary high priority worker threads,
   but our caller might not have that capability.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success. An error code otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-yield">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>yield</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>yield</refname>
 <refpurpose>
     yield the current processor to other threads.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __sched <function>yield </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Do not ever use this function, there's a 99% chance you're doing it wrong.
   </para><para>

   The scheduler is at all times free to pick the calling task as the most
   eligible task to run, if removing the <function><link linkend="API-yield">yield</link></function> call from your code breaks
   it, its already broken.
</para>
</refsect1>
<refsect1>
<title>Typical broken usage is</title>
<para>
   </para><para>

   while (!event)
   <function><link linkend="API-yield">yield</link></function>;
   </para><para>

   where one assumes that <function><link linkend="API-yield">yield</link></function> will let 'the other' process run that will
   make event true. If the current task is a SCHED_FIFO task that will never
   happen. Never use <function><link linkend="API-yield">yield</link></function> as a progress guarantee!!
   </para><para>

   If you want to use <function><link linkend="API-yield">yield</link></function> to wait for something, use <function><link linkend="API-wait-event">wait_event</link></function>.
   If you want to use <function><link linkend="API-yield">yield</link></function> to be 'nice' for others, use <function>cond_resched</function>.
   If you still want to use <function><link linkend="API-yield">yield</link></function>, do not!
</para>
</refsect1>
</refentry>

<refentry id="API-yield-to">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>yield_to</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>yield_to</refname>
 <refpurpose>
     yield the current processor to another thread in your thread group, or accelerate that thread toward the processor it's on.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __sched <function>yield_to </function></funcdef>
   <paramdef>struct task_struct * <parameter>p</parameter></paramdef>
   <paramdef>bool <parameter>preempt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     target task
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>preempt</parameter></term>
   <listitem>
    <para>
     whether task preemption is allowed or not
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It's the caller's job to ensure that the target task struct
   can't go away on us before we can do any checks.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   true (&gt;0) if we indeed boosted the target task.
   false (0) if we failed to boost the target.
   -ESRCH if there's no task to yield to.
</para>
</refsect1>
</refentry>

<!-- kernel/sched/cpupri.c -->
<refentry id="API-cpupri-find">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cpupri_find</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cpupri_find</refname>
 <refpurpose>
  find the best (lowest-pri) CPU in the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>cpupri_find </function></funcdef>
   <paramdef>struct cpupri * <parameter>cp</parameter></paramdef>
   <paramdef>struct task_struct * <parameter>p</parameter></paramdef>
   <paramdef>struct cpumask * <parameter>lowest_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cp</parameter></term>
   <listitem>
    <para>
     The cpupri context
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     The task
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lowest_mask</parameter></term>
   <listitem>
    <para>
     A mask to fill in with selected CPUs (or NULL)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   This function returns the recommended CPUs as calculated during the
   current invocation.  By the time the call returns, the CPUs may have in
   fact changed priorities any number of times.  While not ideal, it is not
   an issue of correctness since the normal rebalancer logic will correct
   any discrepancies created by racing against the uncertainty of the current
   priority configuration.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   (int)bool - CPUs were found
</para>
</refsect1>
</refentry>

<refentry id="API-cpupri-set">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cpupri_set</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cpupri_set</refname>
 <refpurpose>
     update the cpu priority setting
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>cpupri_set </function></funcdef>
   <paramdef>struct cpupri * <parameter>cp</parameter></paramdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
   <paramdef>int <parameter>newpri</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cp</parameter></term>
   <listitem>
    <para>
     The cpupri context
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     The target cpu
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>newpri</parameter></term>
   <listitem>
    <para>
     The priority (INVALID-RT99) to assign to this CPU
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   Assumes cpu_rq(cpu)-&gt;lock is locked
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   (void)
</para>
</refsect1>
</refentry>

<refentry id="API-cpupri-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cpupri_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cpupri_init</refname>
 <refpurpose>
     initialize the cpupri structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>cpupri_init </function></funcdef>
   <paramdef>struct cpupri * <parameter>cp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cp</parameter></term>
   <listitem>
    <para>
     The cpupri context
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   -ENOMEM on memory allocation failure.
</para>
</refsect1>
</refentry>

<refentry id="API-cpupri-cleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cpupri_cleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cpupri_cleanup</refname>
 <refpurpose>
     clean up the cpupri structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>cpupri_cleanup </function></funcdef>
   <paramdef>struct cpupri * <parameter>cp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cp</parameter></term>
   <listitem>
    <para>
     The cpupri context
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- kernel/sched/fair.c -->
<refentry id="API-get-sd-load-idx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_sd_load_idx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_sd_load_idx</refname>
 <refpurpose>
  Obtain the load index for a given sched domain.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>get_sd_load_idx </function></funcdef>
   <paramdef>struct sched_domain * <parameter>sd</parameter></paramdef>
   <paramdef>enum cpu_idle_type <parameter>idle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sd</parameter></term>
   <listitem>
    <para>
     The sched_domain whose load_idx is to be obtained.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>idle</parameter></term>
   <listitem>
    <para>
     The idle status of the CPU for whose sd load_idx is obtained.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The load index.
</para>
</refsect1>
</refentry>

<refentry id="API-update-sg-lb-stats">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>update_sg_lb_stats</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>update_sg_lb_stats</refname>
 <refpurpose>
     Update sched_group's statistics for load balancing.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>update_sg_lb_stats </function></funcdef>
   <paramdef>struct lb_env * <parameter>env</parameter></paramdef>
   <paramdef>struct sched_group * <parameter>group</parameter></paramdef>
   <paramdef>int <parameter>load_idx</parameter></paramdef>
   <paramdef>int <parameter>local_group</parameter></paramdef>
   <paramdef>struct sg_lb_stats * <parameter>sgs</parameter></paramdef>
   <paramdef>bool * <parameter>overload</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>env</parameter></term>
   <listitem>
    <para>
     The load balancing environment.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>group</parameter></term>
   <listitem>
    <para>
     sched_group whose statistics are to be updated.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>load_idx</parameter></term>
   <listitem>
    <para>
     Load index of sched_domain of this_cpu for load calc.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>local_group</parameter></term>
   <listitem>
    <para>
     Does group contain this_cpu.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sgs</parameter></term>
   <listitem>
    <para>
     variable to hold the statistics for this group.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>overload</parameter></term>
   <listitem>
    <para>
     Indicate more than one runnable task for any CPU.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-update-sd-pick-busiest">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>update_sd_pick_busiest</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>update_sd_pick_busiest</refname>
 <refpurpose>
     return 1 on busiest group
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>update_sd_pick_busiest </function></funcdef>
   <paramdef>struct lb_env * <parameter>env</parameter></paramdef>
   <paramdef>struct sd_lb_stats * <parameter>sds</parameter></paramdef>
   <paramdef>struct sched_group * <parameter>sg</parameter></paramdef>
   <paramdef>struct sg_lb_stats * <parameter>sgs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>env</parameter></term>
   <listitem>
    <para>
     The load balancing environment.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sds</parameter></term>
   <listitem>
    <para>
     sched_domain statistics
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sg</parameter></term>
   <listitem>
    <para>
     sched_group candidate to be checked for being the busiest
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sgs</parameter></term>
   <listitem>
    <para>
     sched_group statistics
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Determine if <parameter>sg</parameter> is a busier group than the previously selected
   busiest group.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>true</constant> if <parameter>sg</parameter> is a busier group than the previously selected
   busiest group. <constant>false</constant> otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-update-sd-lb-stats">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>update_sd_lb_stats</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>update_sd_lb_stats</refname>
 <refpurpose>
     Update sched_domain's statistics for load balancing.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>update_sd_lb_stats </function></funcdef>
   <paramdef>struct lb_env * <parameter>env</parameter></paramdef>
   <paramdef>struct sd_lb_stats * <parameter>sds</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>env</parameter></term>
   <listitem>
    <para>
     The load balancing environment.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sds</parameter></term>
   <listitem>
    <para>
     variable to hold the statistics for this sched_domain.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-check-asym-packing">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>check_asym_packing</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>check_asym_packing</refname>
 <refpurpose>
     Check to see if the group is packed into the sched doman.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>check_asym_packing </function></funcdef>
   <paramdef>struct lb_env * <parameter>env</parameter></paramdef>
   <paramdef>struct sd_lb_stats * <parameter>sds</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>env</parameter></term>
   <listitem>
    <para>
     The load balancing environment.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sds</parameter></term>
   <listitem>
    <para>
     Statistics of the sched_domain which is to be packed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   This is primarily intended to used at the sibling level.  Some
   cores like POWER7 prefer to use lower numbered SMT threads.  In the
   case of POWER7, it can move to lower SMT modes only when higher
   threads are idle.  When in lower SMT modes, the threads will
   perform better since they share less core resources.  Hence when we
   have idle threads, we want them to be the higher ones.
   </para><para>

   This packing function is run on idle threads.  It checks to see if
   the busiest CPU in this domain (core in the P7 case) has a higher
   CPU number than the packing function is being run on.  Here we are
   assuming lower CPU number will be equivalent to lower a SMT thread
   number.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 when packing is required and a task should be moved to
   this CPU.  The amount of the imbalance is returned in *imbalance.
</para>
</refsect1>
</refentry>

<refentry id="API-fix-small-imbalance">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fix_small_imbalance</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fix_small_imbalance</refname>
 <refpurpose>
     Calculate the minor imbalance that exists amongst the groups of a sched_domain, during load balancing.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fix_small_imbalance </function></funcdef>
   <paramdef>struct lb_env * <parameter>env</parameter></paramdef>
   <paramdef>struct sd_lb_stats * <parameter>sds</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>env</parameter></term>
   <listitem>
    <para>
     The load balancing environment.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sds</parameter></term>
   <listitem>
    <para>
     Statistics of the sched_domain whose imbalance is to be calculated.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-calculate-imbalance">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>calculate_imbalance</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>calculate_imbalance</refname>
 <refpurpose>
     Calculate the amount of imbalance present within the groups of a given sched_domain during load balance.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>calculate_imbalance </function></funcdef>
   <paramdef>struct lb_env * <parameter>env</parameter></paramdef>
   <paramdef>struct sd_lb_stats * <parameter>sds</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>env</parameter></term>
   <listitem>
    <para>
     load balance environment
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sds</parameter></term>
   <listitem>
    <para>
     statistics of the sched_domain whose imbalance is to be calculated.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-find-busiest-group">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_busiest_group</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_busiest_group</refname>
 <refpurpose>
     Returns the busiest group within the sched_domain if there is an imbalance. If there isn't an imbalance, and the user has opted for power-savings, it returns a group whose CPUs can be put to idle by rebalancing those tasks elsewhere, if such a group exists.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sched_group * <function>find_busiest_group </function></funcdef>
   <paramdef>struct lb_env * <parameter>env</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>env</parameter></term>
   <listitem>
    <para>
     The load balancing environment.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Also calculates the amount of weighted load which should be moved
   to restore balance.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   - The busiest group if imbalance exists.
   - If no imbalance and user has opted for power-savings balance,
   return the least loaded group whose CPUs can be
   put to idle by rebalancing its tasks onto our group.
</para>
</refsect1>
</refentry>

<!-- include/linux/completion.h -->
<refentry id="API-DECLARE-COMPLETION">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>DECLARE_COMPLETION</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>DECLARE_COMPLETION</refname>
 <refpurpose>
  declare and initialize a completion structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>DECLARE_COMPLETION </function></funcdef>
   <paramdef> <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     identifier for the completion structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro declares and initializes a completion structure. Generally used
   for static declarations. You should use the _ONSTACK variant for automatic
   variables.
</para>
</refsect1>
</refentry>

<refentry id="API-DECLARE-COMPLETION-ONSTACK">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>DECLARE_COMPLETION_ONSTACK</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>DECLARE_COMPLETION_ONSTACK</refname>
 <refpurpose>
     declare and initialize a completion structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>DECLARE_COMPLETION_ONSTACK </function></funcdef>
   <paramdef> <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     identifier for the completion structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro declares and initializes a completion structure on the kernel
   stack.
</para>
</refsect1>
</refentry>

<refentry id="API-init-completion">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>init_completion</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>init_completion</refname>
 <refpurpose>
     Initialize a dynamically allocated completion
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>init_completion </function></funcdef>
   <paramdef>struct completion * <parameter>x</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     pointer to completion structure that is to be initialized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This inline function will initialize a dynamically created completion
   structure.
</para>
</refsect1>
</refentry>

<refentry id="API-reinit-completion">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>reinit_completion</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>reinit_completion</refname>
 <refpurpose>
     reinitialize a completion structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>reinit_completion </function></funcdef>
   <paramdef>struct completion * <parameter>x</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     pointer to completion structure that is to be reinitialized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This inline function should be used to reinitialize a completion structure so it can
   be reused. This is especially important after <function>complete_all</function> is used.
</para>
</refsect1>
</refentry>

<!-- kernel/time/timer.c -->
<refentry id="API---round-jiffies">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__round_jiffies</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__round_jiffies</refname>
 <refpurpose>
  function to round jiffies to a full second
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>__round_jiffies </function></funcdef>
   <paramdef>unsigned long <parameter>j</parameter></paramdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>j</parameter></term>
   <listitem>
    <para>
     the time in (absolute) jiffies that should be rounded
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     the processor number on which the timeout will happen
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API---round-jiffies">__round_jiffies</link></function> rounds an absolute time in the future (in jiffies)
   up or down to (approximately) full seconds. This is useful for timers
   for which the exact time they fire does not matter too much, as long as
   they fire approximately every X seconds.
   </para><para>

   By rounding these timers to whole seconds, all such timers will fire
   at the same time, rather than at various times spread out. The goal
   of this is to have the CPU wake up less, which saves power.
   </para><para>

   The exact rounding is skewed for each processor to avoid all
   processors firing at the exact same time, which could lead
   to lock contention or spurious cache line bouncing.
   </para><para>

   The return value is the rounded version of the <parameter>j</parameter> parameter.
</para>
</refsect1>
</refentry>

<refentry id="API---round-jiffies-relative">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__round_jiffies_relative</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__round_jiffies_relative</refname>
 <refpurpose>
     function to round jiffies to a full second
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>__round_jiffies_relative </function></funcdef>
   <paramdef>unsigned long <parameter>j</parameter></paramdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>j</parameter></term>
   <listitem>
    <para>
     the time in (relative) jiffies that should be rounded
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     the processor number on which the timeout will happen
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API---round-jiffies-relative">__round_jiffies_relative</link></function> rounds a time delta  in the future (in jiffies)
   up or down to (approximately) full seconds. This is useful for timers
   for which the exact time they fire does not matter too much, as long as
   they fire approximately every X seconds.
   </para><para>

   By rounding these timers to whole seconds, all such timers will fire
   at the same time, rather than at various times spread out. The goal
   of this is to have the CPU wake up less, which saves power.
   </para><para>

   The exact rounding is skewed for each processor to avoid all
   processors firing at the exact same time, which could lead
   to lock contention or spurious cache line bouncing.
   </para><para>

   The return value is the rounded version of the <parameter>j</parameter> parameter.
</para>
</refsect1>
</refentry>

<refentry id="API-round-jiffies">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>round_jiffies</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>round_jiffies</refname>
 <refpurpose>
     function to round jiffies to a full second
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>round_jiffies </function></funcdef>
   <paramdef>unsigned long <parameter>j</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>j</parameter></term>
   <listitem>
    <para>
     the time in (absolute) jiffies that should be rounded
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API-round-jiffies">round_jiffies</link></function> rounds an absolute time in the future (in jiffies)
   up or down to (approximately) full seconds. This is useful for timers
   for which the exact time they fire does not matter too much, as long as
   they fire approximately every X seconds.
   </para><para>

   By rounding these timers to whole seconds, all such timers will fire
   at the same time, rather than at various times spread out. The goal
   of this is to have the CPU wake up less, which saves power.
   </para><para>

   The return value is the rounded version of the <parameter>j</parameter> parameter.
</para>
</refsect1>
</refentry>

<refentry id="API-round-jiffies-relative">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>round_jiffies_relative</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>round_jiffies_relative</refname>
 <refpurpose>
     function to round jiffies to a full second
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>round_jiffies_relative </function></funcdef>
   <paramdef>unsigned long <parameter>j</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>j</parameter></term>
   <listitem>
    <para>
     the time in (relative) jiffies that should be rounded
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API-round-jiffies-relative">round_jiffies_relative</link></function> rounds a time delta  in the future (in jiffies)
   up or down to (approximately) full seconds. This is useful for timers
   for which the exact time they fire does not matter too much, as long as
   they fire approximately every X seconds.
   </para><para>

   By rounding these timers to whole seconds, all such timers will fire
   at the same time, rather than at various times spread out. The goal
   of this is to have the CPU wake up less, which saves power.
   </para><para>

   The return value is the rounded version of the <parameter>j</parameter> parameter.
</para>
</refsect1>
</refentry>

<refentry id="API---round-jiffies-up">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__round_jiffies_up</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__round_jiffies_up</refname>
 <refpurpose>
     function to round jiffies up to a full second
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>__round_jiffies_up </function></funcdef>
   <paramdef>unsigned long <parameter>j</parameter></paramdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>j</parameter></term>
   <listitem>
    <para>
     the time in (absolute) jiffies that should be rounded
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     the processor number on which the timeout will happen
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the same as <function><link linkend="API---round-jiffies">__round_jiffies</link></function> except that it will never
   round down.  This is useful for timeouts for which the exact time
   of firing does not matter too much, as long as they don't fire too
   early.
</para>
</refsect1>
</refentry>

<refentry id="API---round-jiffies-up-relative">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__round_jiffies_up_relative</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__round_jiffies_up_relative</refname>
 <refpurpose>
     function to round jiffies up to a full second
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>__round_jiffies_up_relative </function></funcdef>
   <paramdef>unsigned long <parameter>j</parameter></paramdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>j</parameter></term>
   <listitem>
    <para>
     the time in (relative) jiffies that should be rounded
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     the processor number on which the timeout will happen
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the same as <function><link linkend="API---round-jiffies-relative">__round_jiffies_relative</link></function> except that it will never
   round down.  This is useful for timeouts for which the exact time
   of firing does not matter too much, as long as they don't fire too
   early.
</para>
</refsect1>
</refentry>

<refentry id="API-round-jiffies-up">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>round_jiffies_up</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>round_jiffies_up</refname>
 <refpurpose>
     function to round jiffies up to a full second
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>round_jiffies_up </function></funcdef>
   <paramdef>unsigned long <parameter>j</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>j</parameter></term>
   <listitem>
    <para>
     the time in (absolute) jiffies that should be rounded
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the same as <function><link linkend="API-round-jiffies">round_jiffies</link></function> except that it will never
   round down.  This is useful for timeouts for which the exact time
   of firing does not matter too much, as long as they don't fire too
   early.
</para>
</refsect1>
</refentry>

<refentry id="API-round-jiffies-up-relative">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>round_jiffies_up_relative</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>round_jiffies_up_relative</refname>
 <refpurpose>
     function to round jiffies up to a full second
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>round_jiffies_up_relative </function></funcdef>
   <paramdef>unsigned long <parameter>j</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>j</parameter></term>
   <listitem>
    <para>
     the time in (relative) jiffies that should be rounded
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the same as <function><link linkend="API-round-jiffies-relative">round_jiffies_relative</link></function> except that it will never
   round down.  This is useful for timeouts for which the exact time
   of firing does not matter too much, as long as they don't fire too
   early.
</para>
</refsect1>
</refentry>

<refentry id="API-set-timer-slack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>set_timer_slack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>set_timer_slack</refname>
 <refpurpose>
     set the allowed slack for a timer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>set_timer_slack </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
   <paramdef>int <parameter>slack_hz</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be modified
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>slack_hz</parameter></term>
   <listitem>
    <para>
     the amount of time (in jiffies) allowed for rounding
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set the amount of time, in jiffies, that a certain timer has
   in terms of slack. By setting this value, the timer subsystem
   will schedule the actual timer somewhere between
   the time <function><link linkend="API-mod-timer">mod_timer</link></function> asks for, and that time plus the slack.
   </para><para>

   By setting the slack to -1, a percentage of the delay is used
   instead.
</para>
</refsect1>
</refentry>

<refentry id="API-init-timer-key">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>init_timer_key</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>init_timer_key</refname>
 <refpurpose>
     initialize a timer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>init_timer_key </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct lock_class_key * <parameter>key</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be initialized
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     timer flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of the timer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>key</parameter></term>
   <listitem>
    <para>
     lockdep class key of the fake lock used for tracking timer
     sync lock dependencies
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API-init-timer-key">init_timer_key</link></function> must be done to a timer prior calling *any* of the
   other timer functions.
</para>
</refsect1>
</refentry>

<refentry id="API-mod-timer-pending">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mod_timer_pending</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mod_timer_pending</refname>
 <refpurpose>
     modify a pending timer's timeout
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mod_timer_pending </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
   <paramdef>unsigned long <parameter>expires</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the pending timer to be modified
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>expires</parameter></term>
   <listitem>
    <para>
     new timeout in jiffies
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API-mod-timer-pending">mod_timer_pending</link></function> is the same for pending timers as <function><link linkend="API-mod-timer">mod_timer</link></function>,
   but will not re-activate and modify already deleted timers.
   </para><para>

   It is useful for unserialized use of timers.
</para>
</refsect1>
</refentry>

<refentry id="API-mod-timer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mod_timer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mod_timer</refname>
 <refpurpose>
     modify a timer's timeout
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mod_timer </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
   <paramdef>unsigned long <parameter>expires</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be modified
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>expires</parameter></term>
   <listitem>
    <para>
     new timeout in jiffies
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API-mod-timer">mod_timer</link></function> is a more efficient way to update the expire field of an
   active timer (if the timer is inactive it will be activated)
   </para><para>

   mod_timer(timer, expires) is equivalent to:
   </para><para>

   del_timer(timer); timer-&gt;expires = expires; add_timer(timer);
   </para><para>

   Note that if there are multiple unserialized concurrent users of the
   same timer, then <function><link linkend="API-mod-timer">mod_timer</link></function> is the only safe way to modify the timeout,
   since <function><link linkend="API-add-timer">add_timer</link></function> cannot modify an already running timer.
   </para><para>

   The function returns whether it has modified a pending timer or not.
   (ie. <function><link linkend="API-mod-timer">mod_timer</link></function> of an inactive timer returns 0, <function><link linkend="API-mod-timer">mod_timer</link></function> of an
   active timer returns 1.)
</para>
</refsect1>
</refentry>

<refentry id="API-mod-timer-pinned">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mod_timer_pinned</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mod_timer_pinned</refname>
 <refpurpose>
     modify a timer's timeout
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mod_timer_pinned </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
   <paramdef>unsigned long <parameter>expires</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be modified
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>expires</parameter></term>
   <listitem>
    <para>
     new timeout in jiffies
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API-mod-timer-pinned">mod_timer_pinned</link></function> is a way to update the expire field of an
   active timer (if the timer is inactive it will be activated)
   and to ensure that the timer is scheduled on the current CPU.
   </para><para>

   Note that this does not prevent the timer from being migrated
   when the current CPU goes offline.  If this is a problem for
   you, use CPU-hotplug notifiers to handle it correctly, for
   example, cancelling the timer when the corresponding CPU goes
   offline.
   </para><para>

   mod_timer_pinned(timer, expires) is equivalent to:
   </para><para>

   del_timer(timer); timer-&gt;expires = expires; add_timer(timer);
</para>
</refsect1>
</refentry>

<refentry id="API-add-timer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>add_timer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>add_timer</refname>
 <refpurpose>
     start a timer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>add_timer </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be added
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The kernel will do a -&gt;function(-&gt;data) callback from the
   timer interrupt at the -&gt;expires point in the future. The
   current time is 'jiffies'.
   </para><para>

   The timer's -&gt;expires, -&gt;function (and if the handler uses it, -&gt;data)
   fields must be set prior calling this function.
   </para><para>

   Timers with an -&gt;expires field in the past will be executed in the next
   timer tick.
</para>
</refsect1>
</refentry>

<refentry id="API-add-timer-on">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>add_timer_on</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>add_timer_on</refname>
 <refpurpose>
     start a timer on a particular CPU
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>add_timer_on </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     the CPU to start it on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is not very scalable on SMP. Double adds are not possible.
</para>
</refsect1>
</refentry>

<refentry id="API-del-timer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>del_timer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>del_timer</refname>
 <refpurpose>
     deactive a timer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>del_timer </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be deactivated
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API-del-timer">del_timer</link></function> deactivates a timer - this works on both active and inactive
   timers.
   </para><para>

   The function returns whether it has deactivated a pending timer or not.
   (ie. <function><link linkend="API-del-timer">del_timer</link></function> of an inactive timer returns 0, <function><link linkend="API-del-timer">del_timer</link></function> of an
   active timer returns 1.)
</para>
</refsect1>
</refentry>

<refentry id="API-try-to-del-timer-sync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>try_to_del_timer_sync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>try_to_del_timer_sync</refname>
 <refpurpose>
     Try to deactivate a timer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>try_to_del_timer_sync </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     timer do del
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function tries to deactivate a timer. Upon successful (ret &gt;= 0)
   exit the timer is not queued and the handler is not running on any CPU.
</para>
</refsect1>
</refentry>

<refentry id="API-del-timer-sync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>del_timer_sync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>del_timer_sync</refname>
 <refpurpose>
     deactivate a timer and wait for the handler to finish.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>del_timer_sync </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be deactivated
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function only differs from <function><link linkend="API-del-timer">del_timer</link></function> on SMP: besides deactivating
   the timer it also makes sure the handler has finished executing on other
   CPUs.
</para>
</refsect1>
<refsect1>
<title>Synchronization rules</title>
<para>
   Callers must prevent restarting of the timer,
   otherwise this function is meaningless. It must not be called from
   interrupt contexts unless the timer is an irqsafe one. The caller must
   not hold locks which would prevent completion of the timer's
   handler. The timer's handler must not call <function><link linkend="API-add-timer-on">add_timer_on</link></function>. Upon exit the
   timer is not queued and the handler is not running on any CPU.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   For !irqsafe timers, you must not hold locks that are held in
   interrupt context while calling this function. Even if the lock has
   nothing to do with the timer in question.  Here's why:
   </para><para>

   CPU0                             CPU1
   ----                             ----
   &lt;SOFTIRQ&gt;
   <function>call_timer_fn</function>;
   base-&gt;running_timer = mytimer;
   spin_lock_irq(somelock);
   &lt;IRQ&gt;
   spin_lock(somelock);
   del_timer_sync(mytimer);
   while (base-&gt;running_timer == mytimer);
   </para><para>

   Now <function><link linkend="API-del-timer-sync">del_timer_sync</link></function> will never return and never release somelock.
   The interrupt on the other CPU is waiting to grab somelock but
   it has interrupted the softirq that CPU0 is waiting to finish.
   </para><para>

   The function returns whether it has deactivated a pending timer or not.
</para>
</refsect1>
</refentry>

<refentry id="API-schedule-timeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>schedule_timeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>schedule_timeout</refname>
 <refpurpose>
     sleep until timeout
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>signed long __sched <function>schedule_timeout </function></funcdef>
   <paramdef>signed long <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     timeout value in jiffies
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Make the current task sleep until <parameter>timeout</parameter> jiffies have
   elapsed. The routine will return immediately unless
   the current task state has been set (see <function>set_current_state</function>).
   </para><para>

   You can set the task state as follows -
   </para><para>

   <constant>TASK_UNINTERRUPTIBLE</constant> - at least <parameter>timeout</parameter> jiffies are guaranteed to
   pass before the routine returns. The routine will return 0
   </para><para>

   <constant>TASK_INTERRUPTIBLE</constant> - the routine may return early if a signal is
   delivered to the current task. In this case the remaining time
   in jiffies will be returned, or 0 if the timer expired in time
   </para><para>

   The current task state is guaranteed to be TASK_RUNNING when this
   routine returns.
   </para><para>

   Specifying a <parameter>timeout</parameter> value of <constant>MAX_SCHEDULE_TIMEOUT</constant> will schedule
   the CPU away without a bound on the timeout. In this case the return
   value will be <constant>MAX_SCHEDULE_TIMEOUT</constant>.
   </para><para>

   In all cases the return value is guaranteed to be non-negative.
</para>
</refsect1>
</refentry>

<refentry id="API-msleep">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>msleep</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>msleep</refname>
 <refpurpose>
     sleep safely even with waitqueue interruptions
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>msleep </function></funcdef>
   <paramdef>unsigned int <parameter>msecs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>msecs</parameter></term>
   <listitem>
    <para>
     Time in milliseconds to sleep for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-msleep-interruptible">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>msleep_interruptible</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>msleep_interruptible</refname>
 <refpurpose>
     sleep waiting for signals
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>msleep_interruptible </function></funcdef>
   <paramdef>unsigned int <parameter>msecs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>msecs</parameter></term>
   <listitem>
    <para>
     Time in milliseconds to sleep for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-usleep-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>usleep_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>usleep_range</refname>
 <refpurpose>
     Drop in replacement for udelay where wakeup is flexible
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __sched <function>usleep_range </function></funcdef>
   <paramdef>unsigned long <parameter>min</parameter></paramdef>
   <paramdef>unsigned long <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     Minimum time in usecs to sleep
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     Maximum time in usecs to sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Wait queues and Wake events</title>
<!-- include/linux/wait.h -->
<refentry id="API-wait-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event</refname>
 <refpurpose>
  sleep until a condition gets true
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_UNINTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true. The <parameter>condition</parameter> is checked each time
   the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-freezable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_freezable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_freezable</refname>
 <refpurpose>
     sleep (or freeze) until a condition gets true
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_freezable </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_INTERRUPTIBLE -- so as not to contribute
   to system load) until the <parameter>condition</parameter> evaluates to true. The
   <parameter>condition</parameter> is checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-timeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_timeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_timeout</refname>
 <refpurpose>
     sleep until a condition gets true or a timeout elapses
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_timeout </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
   <paramdef> <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     timeout, in jiffies
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_UNINTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true. The <parameter>condition</parameter> is checked each time
   the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 if the <parameter>condition</parameter> evaluated to <constant>false</constant> after the <parameter>timeout</parameter> elapsed,
   1 if the <parameter>condition</parameter> evaluated to <constant>true</constant> after the <parameter>timeout</parameter> elapsed,
   or the remaining jiffies (at least 1) if the <parameter>condition</parameter> evaluated
   to <constant>true</constant> before the <parameter>timeout</parameter> elapsed.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-cmd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_cmd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_cmd</refname>
 <refpurpose>
     sleep until a condition gets true
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_cmd </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
   <paramdef> <parameter>cmd1</parameter></paramdef>
   <paramdef> <parameter>cmd2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd1</parameter></term>
   <listitem>
    <para>
     the command will be executed before sleep
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd2</parameter></term>
   <listitem>
    <para>
     the command will be executed after sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_UNINTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true. The <parameter>condition</parameter> is checked each time
   the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-interruptible">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_interruptible</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_interruptible</refname>
 <refpurpose>
     sleep until a condition gets true
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_interruptible </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_INTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true or a signal is received.
   The <parameter>condition</parameter> is checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   The function will return -ERESTARTSYS if it was interrupted by a
   signal and 0 if <parameter>condition</parameter> evaluated to true.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-interruptible-timeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_interruptible_timeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_interruptible_timeout</refname>
 <refpurpose>
     sleep until a condition gets true or a timeout elapses
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_interruptible_timeout </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
   <paramdef> <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     timeout, in jiffies
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_INTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true or a signal is received.
   The <parameter>condition</parameter> is checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 if the <parameter>condition</parameter> evaluated to <constant>false</constant> after the <parameter>timeout</parameter> elapsed,
   1 if the <parameter>condition</parameter> evaluated to <constant>true</constant> after the <parameter>timeout</parameter> elapsed,
   the remaining jiffies (at least 1) if the <parameter>condition</parameter> evaluated
   to <constant>true</constant> before the <parameter>timeout</parameter> elapsed, or -<constant>ERESTARTSYS</constant> if it was
   interrupted by a signal.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-hrtimeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_hrtimeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_hrtimeout</refname>
 <refpurpose>
     sleep until a condition gets true or a timeout elapses
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_hrtimeout </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
   <paramdef> <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     timeout, as a ktime_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_UNINTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true or a signal is received.
   The <parameter>condition</parameter> is checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   The function returns 0 if <parameter>condition</parameter> became true, or -ETIME if the timeout
   elapsed.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-interruptible-hrtimeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_interruptible_hrtimeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_interruptible_hrtimeout</refname>
 <refpurpose>
     sleep until a condition gets true or a timeout elapses
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_interruptible_hrtimeout </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
   <paramdef> <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     timeout, as a ktime_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_INTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true or a signal is received.
   The <parameter>condition</parameter> is checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   The function returns 0 if <parameter>condition</parameter> became true, -ERESTARTSYS if it was
   interrupted by a signal, or -ETIME if the timeout elapsed.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-interruptible-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_interruptible_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_interruptible_locked</refname>
 <refpurpose>
     sleep until a condition gets true
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_interruptible_locked </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_INTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true or a signal is received.
   The <parameter>condition</parameter> is checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   It must be called with wq.lock being held.  This spinlock is
   unlocked while sleeping but <parameter>condition</parameter> testing is done while lock
   is held and when this macro exits the lock is held.
   </para><para>

   The lock is locked/unlocked using <function>spin_lock</function>/<function>spin_unlock</function>
   functions which must match the way they are locked/unlocked outside
   of this macro.
   </para><para>

   <function>wake_up_locked</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   The function will return -ERESTARTSYS if it was interrupted by a
   signal and 0 if <parameter>condition</parameter> evaluated to true.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-interruptible-locked-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_interruptible_locked_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_interruptible_locked_irq</refname>
 <refpurpose>
     sleep until a condition gets true
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_interruptible_locked_irq </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_INTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true or a signal is received.
   The <parameter>condition</parameter> is checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   It must be called with wq.lock being held.  This spinlock is
   unlocked while sleeping but <parameter>condition</parameter> testing is done while lock
   is held and when this macro exits the lock is held.
   </para><para>

   The lock is locked/unlocked using <function>spin_lock_irq</function>/<function>spin_unlock_irq</function>
   functions which must match the way they are locked/unlocked outside
   of this macro.
   </para><para>

   <function>wake_up_locked</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   The function will return -ERESTARTSYS if it was interrupted by a
   signal and 0 if <parameter>condition</parameter> evaluated to true.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-interruptible-exclusive-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_interruptible_exclusive_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_interruptible_exclusive_locked</refname>
 <refpurpose>
     sleep exclusively until a condition gets true
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_interruptible_exclusive_locked </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_INTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true or a signal is received.
   The <parameter>condition</parameter> is checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   It must be called with wq.lock being held.  This spinlock is
   unlocked while sleeping but <parameter>condition</parameter> testing is done while lock
   is held and when this macro exits the lock is held.
   </para><para>

   The lock is locked/unlocked using <function>spin_lock</function>/<function>spin_unlock</function>
   functions which must match the way they are locked/unlocked outside
   of this macro.
   </para><para>

   The process is put on the wait queue with an WQ_FLAG_EXCLUSIVE flag
   set thus when other process waits process on the list if this
   process is awaken further processes are not considered.
   </para><para>

   <function>wake_up_locked</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   The function will return -ERESTARTSYS if it was interrupted by a
   signal and 0 if <parameter>condition</parameter> evaluated to true.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-interruptible-exclusive-locked-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_interruptible_exclusive_locked_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_interruptible_exclusive_locked_irq</refname>
 <refpurpose>
     sleep until a condition gets true
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_interruptible_exclusive_locked_irq </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_INTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true or a signal is received.
   The <parameter>condition</parameter> is checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   It must be called with wq.lock being held.  This spinlock is
   unlocked while sleeping but <parameter>condition</parameter> testing is done while lock
   is held and when this macro exits the lock is held.
   </para><para>

   The lock is locked/unlocked using <function>spin_lock_irq</function>/<function>spin_unlock_irq</function>
   functions which must match the way they are locked/unlocked outside
   of this macro.
   </para><para>

   The process is put on the wait queue with an WQ_FLAG_EXCLUSIVE flag
   set thus when other process waits process on the list if this
   process is awaken further processes are not considered.
   </para><para>

   <function>wake_up_locked</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   The function will return -ERESTARTSYS if it was interrupted by a
   signal and 0 if <parameter>condition</parameter> evaluated to true.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-killable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_killable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_killable</refname>
 <refpurpose>
     sleep until a condition gets true
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_killable </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_KILLABLE) until the
   <parameter>condition</parameter> evaluates to true or a signal is received.
   The <parameter>condition</parameter> is checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   The function will return -ERESTARTSYS if it was interrupted by a
   signal and 0 if <parameter>condition</parameter> evaluated to true.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-lock-irq-cmd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_lock_irq_cmd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_lock_irq_cmd</refname>
 <refpurpose>
     sleep until a condition gets true. The condition is checked under the lock. This is expected to be called with the lock taken.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_lock_irq_cmd </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
   <paramdef> <parameter>lock</parameter></paramdef>
   <paramdef> <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     a locked spinlock_t, which will be released before cmd
     and <function>schedule</function> and reacquired afterwards.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     a command which is invoked outside the critical section before
     sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_UNINTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true. The <parameter>condition</parameter> is checked each time
   the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   This is supposed to be called while holding the lock. The lock is
   dropped before invoking the cmd and going to sleep and is reacquired
   afterwards.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-lock-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_lock_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_lock_irq</refname>
 <refpurpose>
     sleep until a condition gets true. The condition is checked under the lock. This is expected to be called with the lock taken.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_lock_irq </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
   <paramdef> <parameter>lock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     a locked spinlock_t, which will be released before <function>schedule</function>
     and reacquired afterwards.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_UNINTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true. The <parameter>condition</parameter> is checked each time
   the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   This is supposed to be called while holding the lock. The lock is
   dropped before going to sleep and is reacquired afterwards.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-interruptible-lock-irq-cmd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_interruptible_lock_irq_cmd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_interruptible_lock_irq_cmd</refname>
 <refpurpose>
     sleep until a condition gets true. The condition is checked under the lock. This is expected to be called with the lock taken.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_interruptible_lock_irq_cmd </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
   <paramdef> <parameter>lock</parameter></paramdef>
   <paramdef> <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     a locked spinlock_t, which will be released before cmd and
     <function>schedule</function> and reacquired afterwards.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     a command which is invoked outside the critical section before
     sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_INTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true or a signal is received. The <parameter>condition</parameter> is
   checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   This is supposed to be called while holding the lock. The lock is
   dropped before invoking the cmd and going to sleep and is reacquired
   afterwards.
   </para><para>

   The macro will return -ERESTARTSYS if it was interrupted by a signal
   and 0 if <parameter>condition</parameter> evaluated to true.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-interruptible-lock-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_interruptible_lock_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_interruptible_lock_irq</refname>
 <refpurpose>
     sleep until a condition gets true. The condition is checked under the lock. This is expected to be called with the lock taken.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_interruptible_lock_irq </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
   <paramdef> <parameter>lock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     a locked spinlock_t, which will be released before <function>schedule</function>
     and reacquired afterwards.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_INTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true or signal is received. The <parameter>condition</parameter> is
   checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   This is supposed to be called while holding the lock. The lock is
   dropped before going to sleep and is reacquired afterwards.
   </para><para>

   The macro will return -ERESTARTSYS if it was interrupted by a signal
   and 0 if <parameter>condition</parameter> evaluated to true.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-event-interruptible-lock-irq-timeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_event_interruptible_lock_irq_timeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_event_interruptible_lock_irq_timeout</refname>
 <refpurpose>
     sleep until a condition gets true or a timeout elapses. The condition is checked under the lock. This is expected to be called with the lock taken.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>wait_event_interruptible_lock_irq_timeout </function></funcdef>
   <paramdef> <parameter>wq</parameter></paramdef>
   <paramdef> <parameter>condition</parameter></paramdef>
   <paramdef> <parameter>lock</parameter></paramdef>
   <paramdef> <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the waitqueue to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>condition</parameter></term>
   <listitem>
    <para>
     a C expression for the event to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     a locked spinlock_t, which will be released before <function>schedule</function>
     and reacquired afterwards.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     timeout, in jiffies
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The process is put to sleep (TASK_INTERRUPTIBLE) until the
   <parameter>condition</parameter> evaluates to true or signal is received. The <parameter>condition</parameter> is
   checked each time the waitqueue <parameter>wq</parameter> is woken up.
   </para><para>

   <function>wake_up</function> has to be called after changing any variable that could
   change the result of the wait condition.
   </para><para>

   This is supposed to be called while holding the lock. The lock is
   dropped before going to sleep and is reacquired afterwards.
   </para><para>

   The function returns 0 if the <parameter>timeout</parameter> elapsed, -ERESTARTSYS if it
   was interrupted by a signal, and the remaining jiffies otherwise
   if the condition evaluated to true before the timeout elapsed.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-on-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_on_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_on_bit</refname>
 <refpurpose>
     wait for a bit to be cleared
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>wait_on_bit </function></funcdef>
   <paramdef>unsigned long * <parameter>word</parameter></paramdef>
   <paramdef>int <parameter>bit</parameter></paramdef>
   <paramdef>unsigned <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>word</parameter></term>
   <listitem>
    <para>
     the word being waited on, a kernel virtual address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bit</parameter></term>
   <listitem>
    <para>
     the bit of the word being waited on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the task state to sleep in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   There is a standard hashed waitqueue table for generic use. This
   is the part of the hashtable's accessor API that waits on a bit.
   For instance, if one were to have waiters on a bitflag, one would
   call <function><link linkend="API-wait-on-bit">wait_on_bit</link></function> in threads waiting for the bit to clear.
   One uses <function><link linkend="API-wait-on-bit">wait_on_bit</link></function> where one is waiting for the bit to clear,
   but has no intention of setting it.
   Returned value will be zero if the bit was cleared, or non-zero
   if the process received a signal and the mode permitted wakeup
   on that signal.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-on-bit-io">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_on_bit_io</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_on_bit_io</refname>
 <refpurpose>
     wait for a bit to be cleared
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>wait_on_bit_io </function></funcdef>
   <paramdef>unsigned long * <parameter>word</parameter></paramdef>
   <paramdef>int <parameter>bit</parameter></paramdef>
   <paramdef>unsigned <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>word</parameter></term>
   <listitem>
    <para>
     the word being waited on, a kernel virtual address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bit</parameter></term>
   <listitem>
    <para>
     the bit of the word being waited on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the task state to sleep in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use the standard hashed waitqueue table to wait for a bit
   to be cleared.  This is similar to <function><link linkend="API-wait-on-bit">wait_on_bit</link></function>, but calls
   <function>io_schedule</function> instead of <function>schedule</function> for the actual waiting.
   </para><para>

   Returned value will be zero if the bit was cleared, or non-zero
   if the process received a signal and the mode permitted wakeup
   on that signal.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-on-bit-timeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_on_bit_timeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_on_bit_timeout</refname>
 <refpurpose>
     wait for a bit to be cleared or a timeout elapses
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>wait_on_bit_timeout </function></funcdef>
   <paramdef>unsigned long * <parameter>word</parameter></paramdef>
   <paramdef>int <parameter>bit</parameter></paramdef>
   <paramdef>unsigned <parameter>mode</parameter></paramdef>
   <paramdef>unsigned long <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>word</parameter></term>
   <listitem>
    <para>
     the word being waited on, a kernel virtual address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bit</parameter></term>
   <listitem>
    <para>
     the bit of the word being waited on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the task state to sleep in
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     timeout, in jiffies
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use the standard hashed waitqueue table to wait for a bit
   to be cleared. This is similar to <function><link linkend="API-wait-on-bit">wait_on_bit</link></function>, except also takes a
   timeout parameter.
   </para><para>

   Returned value will be zero if the bit was cleared before the
   <parameter>timeout</parameter> elapsed, or non-zero if the <parameter>timeout</parameter> elapsed or process
   received a signal and the mode permitted wakeup on that signal.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-on-bit-action">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_on_bit_action</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_on_bit_action</refname>
 <refpurpose>
     wait for a bit to be cleared
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>wait_on_bit_action </function></funcdef>
   <paramdef>unsigned long * <parameter>word</parameter></paramdef>
   <paramdef>int <parameter>bit</parameter></paramdef>
   <paramdef>wait_bit_action_f * <parameter>action</parameter></paramdef>
   <paramdef>unsigned <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>word</parameter></term>
   <listitem>
    <para>
     the word being waited on, a kernel virtual address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bit</parameter></term>
   <listitem>
    <para>
     the bit of the word being waited on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>action</parameter></term>
   <listitem>
    <para>
     the function used to sleep, which may take special actions
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the task state to sleep in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use the standard hashed waitqueue table to wait for a bit
   to be cleared, and allow the waiting action to be specified.
   This is like <function><link linkend="API-wait-on-bit">wait_on_bit</link></function> but allows fine control of how the waiting
   is done.
   </para><para>

   Returned value will be zero if the bit was cleared, or non-zero
   if the process received a signal and the mode permitted wakeup
   on that signal.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-on-bit-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_on_bit_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_on_bit_lock</refname>
 <refpurpose>
     wait for a bit to be cleared, when wanting to set it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>wait_on_bit_lock </function></funcdef>
   <paramdef>unsigned long * <parameter>word</parameter></paramdef>
   <paramdef>int <parameter>bit</parameter></paramdef>
   <paramdef>unsigned <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>word</parameter></term>
   <listitem>
    <para>
     the word being waited on, a kernel virtual address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bit</parameter></term>
   <listitem>
    <para>
     the bit of the word being waited on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the task state to sleep in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   There is a standard hashed waitqueue table for generic use. This
   is the part of the hashtable's accessor API that waits on a bit
   when one intends to set it, for instance, trying to lock bitflags.
   For instance, if one were to have waiters trying to set bitflag
   and waiting for it to clear before setting it, one would call
   <function><link linkend="API-wait-on-bit">wait_on_bit</link></function> in threads waiting to be able to set the bit.
   One uses <function><link linkend="API-wait-on-bit-lock">wait_on_bit_lock</link></function> where one is waiting for the bit to
   clear with the intention of setting it, and when done, clearing it.
   </para><para>

   Returns zero if the bit was (eventually) found to be clear and was
   set.  Returns non-zero if a signal was delivered to the process and
   the <parameter>mode</parameter> allows that signal to wake the process.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-on-bit-lock-io">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_on_bit_lock_io</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_on_bit_lock_io</refname>
 <refpurpose>
     wait for a bit to be cleared, when wanting to set it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>wait_on_bit_lock_io </function></funcdef>
   <paramdef>unsigned long * <parameter>word</parameter></paramdef>
   <paramdef>int <parameter>bit</parameter></paramdef>
   <paramdef>unsigned <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>word</parameter></term>
   <listitem>
    <para>
     the word being waited on, a kernel virtual address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bit</parameter></term>
   <listitem>
    <para>
     the bit of the word being waited on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the task state to sleep in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use the standard hashed waitqueue table to wait for a bit
   to be cleared and then to atomically set it.  This is similar
   to <function><link linkend="API-wait-on-bit">wait_on_bit</link></function>, but calls <function>io_schedule</function> instead of <function>schedule</function>
   for the actual waiting.
   </para><para>

   Returns zero if the bit was (eventually) found to be clear and was
   set.  Returns non-zero if a signal was delivered to the process and
   the <parameter>mode</parameter> allows that signal to wake the process.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-on-bit-lock-action">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_on_bit_lock_action</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_on_bit_lock_action</refname>
 <refpurpose>
     wait for a bit to be cleared, when wanting to set it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>wait_on_bit_lock_action </function></funcdef>
   <paramdef>unsigned long * <parameter>word</parameter></paramdef>
   <paramdef>int <parameter>bit</parameter></paramdef>
   <paramdef>wait_bit_action_f * <parameter>action</parameter></paramdef>
   <paramdef>unsigned <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>word</parameter></term>
   <listitem>
    <para>
     the word being waited on, a kernel virtual address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bit</parameter></term>
   <listitem>
    <para>
     the bit of the word being waited on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>action</parameter></term>
   <listitem>
    <para>
     the function used to sleep, which may take special actions
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the task state to sleep in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use the standard hashed waitqueue table to wait for a bit
   to be cleared and then to set it, and allow the waiting action
   to be specified.
   This is like <function><link linkend="API-wait-on-bit">wait_on_bit</link></function> but allows fine control of how the waiting
   is done.
   </para><para>

   Returns zero if the bit was (eventually) found to be clear and was
   set.  Returns non-zero if a signal was delivered to the process and
   the <parameter>mode</parameter> allows that signal to wake the process.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-on-atomic-t">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_on_atomic_t</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_on_atomic_t</refname>
 <refpurpose>
     Wait for an atomic_t to become 0
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>wait_on_atomic_t </function></funcdef>
   <paramdef>atomic_t * <parameter>val</parameter></paramdef>
   <paramdef>int (*<parameter>action</parameter>)
     <funcparams>atomic_t *</funcparams></paramdef>
   <paramdef>unsigned <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     The atomic value being waited on, a kernel virtual address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>action</parameter></term>
   <listitem>
    <para>
     the function used to sleep, which may take special actions
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the task state to sleep in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Wait for an atomic_t to become 0.  We abuse the bit-wait waitqueue table for
   the purpose of getting a waitqueue, but we set the key to a bit number
   outside of the target 'word'.
</para>
</refsect1>
</refentry>

<!-- kernel/sched/wait.c -->
<refentry id="API---wake-up">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__wake_up</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__wake_up</refname>
 <refpurpose>
  wake up threads blocked on a waitqueue.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__wake_up </function></funcdef>
   <paramdef>wait_queue_head_t * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>mode</parameter></paramdef>
   <paramdef>int <parameter>nr_exclusive</parameter></paramdef>
   <paramdef>void * <parameter>key</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the waitqueue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     which threads
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_exclusive</parameter></term>
   <listitem>
    <para>
     how many wake-one or wake-many threads to wake up
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>key</parameter></term>
   <listitem>
    <para>
     is directly passed to the wakeup function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It may be assumed that this function implies a write memory barrier before
   changing the task state if and only if any tasks are woken up.
</para>
</refsect1>
</refentry>

<refentry id="API---wake-up-sync-key">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__wake_up_sync_key</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__wake_up_sync_key</refname>
 <refpurpose>
     wake up threads blocked on a waitqueue.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__wake_up_sync_key </function></funcdef>
   <paramdef>wait_queue_head_t * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>mode</parameter></paramdef>
   <paramdef>int <parameter>nr_exclusive</parameter></paramdef>
   <paramdef>void * <parameter>key</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the waitqueue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     which threads
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_exclusive</parameter></term>
   <listitem>
    <para>
     how many wake-one or wake-many threads to wake up
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>key</parameter></term>
   <listitem>
    <para>
     opaque value to be passed to wakeup targets
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The sync wakeup differs that the waker knows that it will schedule
   away soon, so while the target thread will be woken up, it will not
   be migrated to another CPU - ie. the two threads are 'synchronized'
   with each other. This can prevent needless bouncing between CPUs.
   </para><para>

   On UP it can prevent extra preemption.
   </para><para>

   It may be assumed that this function implies a write memory barrier before
   changing the task state if and only if any tasks are woken up.
</para>
</refsect1>
</refentry>

<refentry id="API-finish-wait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>finish_wait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>finish_wait</refname>
 <refpurpose>
     clean up after waiting in a queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>finish_wait </function></funcdef>
   <paramdef>wait_queue_head_t * <parameter>q</parameter></paramdef>
   <paramdef>wait_queue_t * <parameter>wait</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     waitqueue waited on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wait</parameter></term>
   <listitem>
    <para>
     wait descriptor
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets current thread back to running state and removes
   the wait descriptor from the given waitqueue if still
   queued.
</para>
</refsect1>
</refentry>

<refentry id="API-abort-exclusive-wait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>abort_exclusive_wait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>abort_exclusive_wait</refname>
 <refpurpose>
     abort exclusive waiting in a queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>abort_exclusive_wait </function></funcdef>
   <paramdef>wait_queue_head_t * <parameter>q</parameter></paramdef>
   <paramdef>wait_queue_t * <parameter>wait</parameter></paramdef>
   <paramdef>unsigned int <parameter>mode</parameter></paramdef>
   <paramdef>void * <parameter>key</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     waitqueue waited on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wait</parameter></term>
   <listitem>
    <para>
     wait descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     runstate of the waiter to be woken
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>key</parameter></term>
   <listitem>
    <para>
     key to identify a wait bit queue or <constant>NULL</constant>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets current thread back to running state and removes
   the wait descriptor from the given waitqueue if still
   queued.
   </para><para>

   Wakes up the next waiter if the caller is concurrently
   woken up through the queue.
   </para><para>

   This prevents waiter starvation where an exclusive waiter
   aborts and is woken up concurrently and no one wakes up
   the next waiter.
</para>
</refsect1>
</refentry>

<refentry id="API-wake-up-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wake_up_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wake_up_bit</refname>
 <refpurpose>
     wake up a waiter on a bit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>wake_up_bit </function></funcdef>
   <paramdef>void * <parameter>word</parameter></paramdef>
   <paramdef>int <parameter>bit</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>word</parameter></term>
   <listitem>
    <para>
     the word being waited on, a kernel virtual address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bit</parameter></term>
   <listitem>
    <para>
     the bit of the word being waited on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   There is a standard hashed waitqueue table for generic use. This
   is the part of the hashtable's accessor API that wakes up waiters
   on a bit. For instance, if one were to have waiters on a bitflag,
   one would call <function><link linkend="API-wake-up-bit">wake_up_bit</link></function> after clearing the bit.
   </para><para>

   In order for this to function properly, as it uses <function>waitqueue_active</function>
   internally, some kind of memory barrier must be done prior to calling
   this. Typically, this will be <function>smp_mb__after_atomic</function>, but in some
   cases where bitflags are manipulated non-atomically under a lock, one
   may need to use a less regular barrier, such fs/inode.c's <function>smp_mb</function>,
   because <function>spin_unlock</function> does not guarantee a memory barrier.
</para>
</refsect1>
</refentry>

<refentry id="API-wake-up-atomic-t">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wake_up_atomic_t</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wake_up_atomic_t</refname>
 <refpurpose>
     Wake up a waiter on a atomic_t
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>wake_up_atomic_t </function></funcdef>
   <paramdef>atomic_t * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     The atomic_t being waited on, a kernel virtual address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Wake up anyone waiting for the atomic_t to go to zero.
   </para><para>

   Abuse the bit-waker function and its waitqueue hash table set (the atomic_t
   check is done by the waiter's wake function, not the by the waker itself).
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>High-resolution timers</title>
<!-- include/linux/ktime.h -->
<refentry id="API-ktime-set">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_set</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_set</refname>
 <refpurpose>
  Set a ktime_t variable from a seconds/nanoseconds value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ktime_t <function>ktime_set </function></funcdef>
   <paramdef>const s64 <parameter>secs</parameter></paramdef>
   <paramdef>const unsigned long <parameter>nsecs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>secs</parameter></term>
   <listitem>
    <para>
     seconds to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nsecs</parameter></term>
   <listitem>
    <para>
     nanoseconds to set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The ktime_t representation of the value.
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-equal">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_equal</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_equal</refname>
 <refpurpose>
     Compares two ktime_t variables to see if they are equal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ktime_equal </function></funcdef>
   <paramdef>const ktime_t <parameter>cmp1</parameter></paramdef>
   <paramdef>const ktime_t <parameter>cmp2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmp1</parameter></term>
   <listitem>
    <para>
     comparable1
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmp2</parameter></term>
   <listitem>
    <para>
     comparable2
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Compare two ktime_t variables.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 if equal.
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-compare">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_compare</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_compare</refname>
 <refpurpose>
     Compares two ktime_t variables for less, greater or equal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ktime_compare </function></funcdef>
   <paramdef>const ktime_t <parameter>cmp1</parameter></paramdef>
   <paramdef>const ktime_t <parameter>cmp2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmp1</parameter></term>
   <listitem>
    <para>
     comparable1
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmp2</parameter></term>
   <listitem>
    <para>
     comparable2
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   ...
   cmp1  &lt; cmp2: return &lt;0
   cmp1 == cmp2: return 0
   cmp1  &gt; cmp2: return &gt;0
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-after">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_after</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_after</refname>
 <refpurpose>
     Compare if a ktime_t value is bigger than another one.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>ktime_after </function></funcdef>
   <paramdef>const ktime_t <parameter>cmp1</parameter></paramdef>
   <paramdef>const ktime_t <parameter>cmp2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmp1</parameter></term>
   <listitem>
    <para>
     comparable1
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmp2</parameter></term>
   <listitem>
    <para>
     comparable2
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   true if cmp1 happened after cmp2.
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-before">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_before</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_before</refname>
 <refpurpose>
     Compare if a ktime_t value is smaller than another one.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>ktime_before </function></funcdef>
   <paramdef>const ktime_t <parameter>cmp1</parameter></paramdef>
   <paramdef>const ktime_t <parameter>cmp2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmp1</parameter></term>
   <listitem>
    <para>
     comparable1
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmp2</parameter></term>
   <listitem>
    <para>
     comparable2
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   true if cmp1 happened before cmp2.
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-to-timespec-cond">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_to_timespec_cond</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_to_timespec_cond</refname>
 <refpurpose>
     convert a ktime_t variable to timespec format only if the variable contains data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>ktime_to_timespec_cond </function></funcdef>
   <paramdef>const ktime_t <parameter>kt</parameter></paramdef>
   <paramdef>struct timespec * <parameter>ts</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kt</parameter></term>
   <listitem>
    <para>
     the ktime_t variable to convert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ts</parameter></term>
   <listitem>
    <para>
     the timespec variable to store the result in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>true</constant> if there was a successful conversion, <constant>false</constant> if kt was 0.
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-to-timespec64-cond">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_to_timespec64_cond</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_to_timespec64_cond</refname>
 <refpurpose>
     convert a ktime_t variable to timespec64 format only if the variable contains data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>ktime_to_timespec64_cond </function></funcdef>
   <paramdef>const ktime_t <parameter>kt</parameter></paramdef>
   <paramdef>struct timespec64 * <parameter>ts</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kt</parameter></term>
   <listitem>
    <para>
     the ktime_t variable to convert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ts</parameter></term>
   <listitem>
    <para>
     the timespec variable to store the result in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>true</constant> if there was a successful conversion, <constant>false</constant> if kt was 0.
</para>
</refsect1>
</refentry>

<!-- include/linux/hrtimer.h -->
<refentry id="API-struct-hrtimer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hrtimer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hrtimer</refname>
 <refpurpose>
  the basic hrtimer structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hrtimer {
  struct timerqueue_node node;
  ktime_t _softexpires;
  enum hrtimer_restart		(* function) (struct hrtimer *);
  struct hrtimer_clock_base * base;
  u8 state;
  u8 is_rel;
#ifdef CONFIG_TIMER_STATS
  int start_pid;
  void * start_site;
  char start_comm[16];
#endif
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>node</term>
      <listitem><para>
timerqueue node, which also manages node.expires,
the absolute expiry time in the hrtimers internal
representation. The time is related to the clock on
which the timer is based. Is setup by adding
slack to the _softexpires value. For non range timers
identical to _softexpires.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>_softexpires</term>
      <listitem><para>
the absolute earliest expiry time of the hrtimer.
The time which was given as expiry time when the timer
was armed.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>function</term>
      <listitem><para>
timer expiry callback function
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>base</term>
      <listitem><para>
pointer to the timer base (per cpu and per clock)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>state</term>
      <listitem><para>
state information (See bit values above)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>is_rel</term>
      <listitem><para>
Set if the timer was armed relative
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start_pid</term>
      <listitem><para>
timer statistics field to store the pid of the task which
started the timer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start_site</term>
      <listitem><para>
timer statistics field to store the site where the timer
was started
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start_comm[16]</term>
      <listitem><para>
timer statistics field to store the name of the process which
started the timer
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   The hrtimer structure must be initialized by <function><link linkend="API-hrtimer-init">hrtimer_init</link></function>
</para>
</refsect1>
</refentry>

<refentry id="API-struct-hrtimer-sleeper">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hrtimer_sleeper</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hrtimer_sleeper</refname>
 <refpurpose>
     simple sleeper structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hrtimer_sleeper {
  struct hrtimer timer;
  struct task_struct * task;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>timer</term>
      <listitem><para>
   embedded timer structure
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>task</term>
      <listitem><para>
   task to wake up
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   task is set to NULL, when the timer expires.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-hrtimer-clock-base">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hrtimer_clock_base</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hrtimer_clock_base</refname>
 <refpurpose>
     the timer base for a specific clock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hrtimer_clock_base {
  struct hrtimer_cpu_base * cpu_base;
  int index;
  clockid_t clockid;
  struct timerqueue_head active;
  ktime_t (* get_time) (void);
  ktime_t offset;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>cpu_base</term>
      <listitem><para>
   per cpu clock base
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>index</term>
      <listitem><para>
   clock type index for per_cpu support when moving a
   timer to a base on another cpu.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>clockid</term>
      <listitem><para>
   clock id for per_cpu support
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>active</term>
      <listitem><para>
   red black tree root node for the active timers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_time</term>
      <listitem><para>
   function to retrieve the current time of the clock
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>offset</term>
      <listitem><para>
   offset of this clock to the monotonic base
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-hrtimer-start">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hrtimer_start</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hrtimer_start</refname>
 <refpurpose>
     (re)start an hrtimer on the current CPU
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hrtimer_start </function></funcdef>
   <paramdef><link linkend="API-struct-hrtimer">struct hrtimer</link> * <parameter>timer</parameter></paramdef>
   <paramdef>ktime_t <parameter>tim</parameter></paramdef>
   <paramdef>const enum hrtimer_mode <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tim</parameter></term>
   <listitem>
    <para>
     expiry time
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     expiry mode: absolute (HRTIMER_MODE_ABS) or
     relative (HRTIMER_MODE_REL)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-hrtimer-forward-now">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hrtimer_forward_now</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hrtimer_forward_now</refname>
 <refpurpose>
     forward the timer expiry so it expires after now
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u64 <function>hrtimer_forward_now </function></funcdef>
   <paramdef><link linkend="API-struct-hrtimer">struct hrtimer</link> * <parameter>timer</parameter></paramdef>
   <paramdef>ktime_t <parameter>interval</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     hrtimer to forward
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>interval</parameter></term>
   <listitem>
    <para>
     the interval to forward
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Forward the timer expiry so it will expire after the current time
   of the hrtimer clock base. Returns the number of overruns.
   </para><para>

   Can be safely called from the callback function of <parameter>timer</parameter>. If
   called from other contexts <parameter>timer</parameter> must neither be enqueued nor
   running the callback and the caller needs to take care of
   serialization.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   This only updates the timer expiry value and does not requeue
   the timer.
</para>
</refsect1>
</refentry>

<!-- kernel/time/hrtimer.c -->
<refentry id="API-hrtimer-forward">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hrtimer_forward</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hrtimer_forward</refname>
 <refpurpose>
  forward the timer expiry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u64 <function>hrtimer_forward </function></funcdef>
   <paramdef><link linkend="API-struct-hrtimer">struct hrtimer</link> * <parameter>timer</parameter></paramdef>
   <paramdef>ktime_t <parameter>now</parameter></paramdef>
   <paramdef>ktime_t <parameter>interval</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     hrtimer to forward
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>now</parameter></term>
   <listitem>
    <para>
     forward past this time
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>interval</parameter></term>
   <listitem>
    <para>
     the interval to forward
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Forward the timer expiry so it will expire in the future.
   Returns the number of overruns.
   </para><para>

   Can be safely called from the callback function of <parameter>timer</parameter>. If
   called from other contexts <parameter>timer</parameter> must neither be enqueued nor
   running the callback and the caller needs to take care of
   serialization.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   This only updates the timer expiry value and does not requeue
   the timer.
</para>
</refsect1>
</refentry>

<refentry id="API-hrtimer-start-range-ns">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hrtimer_start_range_ns</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hrtimer_start_range_ns</refname>
 <refpurpose>
     (re)start an hrtimer on the current CPU
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hrtimer_start_range_ns </function></funcdef>
   <paramdef><link linkend="API-struct-hrtimer">struct hrtimer</link> * <parameter>timer</parameter></paramdef>
   <paramdef>ktime_t <parameter>tim</parameter></paramdef>
   <paramdef>unsigned long <parameter>delta_ns</parameter></paramdef>
   <paramdef>const enum hrtimer_mode <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tim</parameter></term>
   <listitem>
    <para>
     expiry time
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delta_ns</parameter></term>
   <listitem>
    <para>
     "slack" range for the timer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     expiry mode: absolute (HRTIMER_MODE_ABS) or
     relative (HRTIMER_MODE_REL)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-hrtimer-try-to-cancel">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hrtimer_try_to_cancel</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hrtimer_try_to_cancel</refname>
 <refpurpose>
     try to deactivate a timer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hrtimer_try_to_cancel </function></funcdef>
   <paramdef><link linkend="API-struct-hrtimer">struct hrtimer</link> * <parameter>timer</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     hrtimer to stop
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 when the timer was not active
   1 when the timer was active
   -1 when the timer is currently excuting the callback function and
   cannot be stopped
</para>
</refsect1>
</refentry>

<refentry id="API-hrtimer-cancel">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hrtimer_cancel</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hrtimer_cancel</refname>
 <refpurpose>
     cancel a timer and wait for the handler to finish.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hrtimer_cancel </function></funcdef>
   <paramdef><link linkend="API-struct-hrtimer">struct hrtimer</link> * <parameter>timer</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be cancelled
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 when the timer was not active
   1 when the timer was active
</para>
</refsect1>
</refentry>

<refentry id="API---hrtimer-get-remaining">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__hrtimer_get_remaining</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__hrtimer_get_remaining</refname>
 <refpurpose>
     get remaining time for the timer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ktime_t <function>__hrtimer_get_remaining </function></funcdef>
   <paramdef><link linkend="API-struct-hrtimer">const struct hrtimer</link> * <parameter>timer</parameter></paramdef>
   <paramdef>bool <parameter>adjust</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>adjust</parameter></term>
   <listitem>
    <para>
     adjust relative timers when CONFIG_TIME_LOW_RES=y
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-hrtimer-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hrtimer_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hrtimer_init</refname>
 <refpurpose>
     initialize a timer to the given clock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hrtimer_init </function></funcdef>
   <paramdef><link linkend="API-struct-hrtimer">struct hrtimer</link> * <parameter>timer</parameter></paramdef>
   <paramdef>clockid_t <parameter>clock_id</parameter></paramdef>
   <paramdef>enum hrtimer_mode <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be initialized
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>clock_id</parameter></term>
   <listitem>
    <para>
     the clock to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     timer mode abs/rel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-schedule-hrtimeout-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>schedule_hrtimeout_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>schedule_hrtimeout_range</refname>
 <refpurpose>
     sleep until timeout
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __sched <function>schedule_hrtimeout_range </function></funcdef>
   <paramdef>ktime_t * <parameter>expires</parameter></paramdef>
   <paramdef>unsigned long <parameter>delta</parameter></paramdef>
   <paramdef>const enum hrtimer_mode <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>expires</parameter></term>
   <listitem>
    <para>
     timeout value (ktime_t)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delta</parameter></term>
   <listitem>
    <para>
     slack in expires timeout (ktime_t)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     timer mode, HRTIMER_MODE_ABS or HRTIMER_MODE_REL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Make the current task sleep until the given expiry time has
   elapsed. The routine will return immediately unless
   the current task state has been set (see <function>set_current_state</function>).
   </para><para>

   The <parameter>delta</parameter> argument gives the kernel the freedom to schedule the
   actual wakeup to a time that is both power and performance friendly.
   The kernel give the normal best effort behavior for <quote><parameter>expires</parameter>+<parameter>delta</parameter></quote>,
   but may decide to fire the timer earlier, but no earlier than <parameter>expires</parameter>.
   </para><para>

   You can set the task state as follows -
   </para><para>

   <constant>TASK_UNINTERRUPTIBLE</constant> - at least <parameter>timeout</parameter> time is guaranteed to
   pass before the routine returns.
   </para><para>

   <constant>TASK_INTERRUPTIBLE</constant> - the routine may return early if a signal is
   delivered to the current task.
   </para><para>

   The current task state is guaranteed to be TASK_RUNNING when this
   routine returns.
   </para><para>

   Returns 0 when the timer has expired otherwise -EINTR
</para>
</refsect1>
</refentry>

<refentry id="API-schedule-hrtimeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>schedule_hrtimeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>schedule_hrtimeout</refname>
 <refpurpose>
     sleep until timeout
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __sched <function>schedule_hrtimeout </function></funcdef>
   <paramdef>ktime_t * <parameter>expires</parameter></paramdef>
   <paramdef>const enum hrtimer_mode <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>expires</parameter></term>
   <listitem>
    <para>
     timeout value (ktime_t)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     timer mode, HRTIMER_MODE_ABS or HRTIMER_MODE_REL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Make the current task sleep until the given expiry time has
   elapsed. The routine will return immediately unless
   the current task state has been set (see <function>set_current_state</function>).
   </para><para>

   You can set the task state as follows -
   </para><para>

   <constant>TASK_UNINTERRUPTIBLE</constant> - at least <parameter>timeout</parameter> time is guaranteed to
   pass before the routine returns.
   </para><para>

   <constant>TASK_INTERRUPTIBLE</constant> - the routine may return early if a signal is
   delivered to the current task.
   </para><para>

   The current task state is guaranteed to be TASK_RUNNING when this
   routine returns.
   </para><para>

   Returns 0 when the timer has expired otherwise -EINTR
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Workqueues and Kevents</title>
<!-- include/linux/workqueue.h -->
<refentry id="API-work-pending">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>work_pending</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>work_pending</refname>
 <refpurpose>
  Find out whether a work item is currently pending
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>work_pending </function></funcdef>
   <paramdef> <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     The work item in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-delayed-work-pending">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>delayed_work_pending</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>delayed_work_pending</refname>
 <refpurpose>
     Find out whether a delayable work item is currently pending
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>delayed_work_pending </function></funcdef>
   <paramdef> <parameter>w</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>w</parameter></term>
   <listitem>
    <para>
     The work item in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-alloc-workqueue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>alloc_workqueue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>alloc_workqueue</refname>
 <refpurpose>
     allocate a workqueue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>alloc_workqueue </function></funcdef>
   <paramdef> <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>flags</parameter></paramdef>
   <paramdef> <parameter>max_active</parameter></paramdef>
   <paramdef> <parameter>args...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     printf format for the name of the workqueue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     WQ_* flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_active</parameter></term>
   <listitem>
    <para>
     max in-flight work items, 0 for default
     <parameter>args</parameter>...: args for <parameter>fmt</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a workqueue with the specified parameters.  For detailed
   information on WQ_* flags, please refer to Documentation/workqueue.txt.
   </para><para>

   The __lock_name macro dance is to guarantee that single lock_class_key
   doesn't end up with different namesm, which isn't allowed by lockdep.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to the allocated workqueue on success, <constant>NULL</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-alloc-ordered-workqueue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>alloc_ordered_workqueue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>alloc_ordered_workqueue</refname>
 <refpurpose>
     allocate an ordered workqueue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>alloc_ordered_workqueue </function></funcdef>
   <paramdef> <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>flags</parameter></paramdef>
   <paramdef> <parameter>args...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     printf format for the name of the workqueue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     WQ_* flags (only WQ_FREEZABLE and WQ_MEM_RECLAIM are meaningful)
     <parameter>args</parameter>...: args for <parameter>fmt</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate an ordered workqueue.  An ordered workqueue executes at
   most one work item at any given time in the queued order.  They are
   implemented as unbound workqueues with <parameter>max_active</parameter> of one.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to the allocated workqueue on success, <constant>NULL</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-queue-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>queue_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>queue_work</refname>
 <refpurpose>
     queue work on a workqueue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>queue_work </function></funcdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     work to queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns <constant>false</constant> if <parameter>work</parameter> was already on a queue, <constant>true</constant> otherwise.
   </para><para>

   We queue the work to the CPU on which it was submitted, but if the CPU dies
   it can be processed by another CPU.
</para>
</refsect1>
</refentry>

<refentry id="API-queue-delayed-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>queue_delayed_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>queue_delayed_work</refname>
 <refpurpose>
     queue work on a workqueue after delay
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>queue_delayed_work </function></funcdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
   <paramdef>unsigned long <parameter>delay</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     delayable work to queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delay</parameter></term>
   <listitem>
    <para>
     number of jiffies to wait before queueing
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Equivalent to <function><link linkend="API-queue-delayed-work-on">queue_delayed_work_on</link></function> but tries to use the local CPU.
</para>
</refsect1>
</refentry>

<refentry id="API-mod-delayed-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mod_delayed_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mod_delayed_work</refname>
 <refpurpose>
     modify delay of or queue a delayed work
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>mod_delayed_work </function></funcdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
   <paramdef>unsigned long <parameter>delay</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     work to queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delay</parameter></term>
   <listitem>
    <para>
     number of jiffies to wait before queueing
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API-mod-delayed-work-on">mod_delayed_work_on</link></function> on local CPU.
</para>
</refsect1>
</refentry>

<refentry id="API-schedule-work-on">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>schedule_work_on</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>schedule_work_on</refname>
 <refpurpose>
     put work task on a specific cpu
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>schedule_work_on </function></funcdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     cpu to put the work task on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     job to be done
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This puts a job on a specific cpu
</para>
</refsect1>
</refentry>

<refentry id="API-schedule-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>schedule_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>schedule_work</refname>
 <refpurpose>
     put work task in global workqueue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>schedule_work </function></funcdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     job to be done
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns <constant>false</constant> if <parameter>work</parameter> was already on the kernel-global workqueue and
   <constant>true</constant> otherwise.
   </para><para>

   This puts a job in the kernel-global workqueue if it was not already
   queued and leaves it in the same position on the kernel-global
   workqueue otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-flush-scheduled-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>flush_scheduled_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>flush_scheduled_work</refname>
 <refpurpose>
     ensure that any scheduled work has run to completion.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>flush_scheduled_work </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Forces execution of the kernel-global workqueue and blocks until its
   completion.
   </para><para>

   Think twice before calling this function!  It's very easy to get into
   trouble if you don't take great care.  Either of the following situations
</para>
</refsect1>
<refsect1>
<title>will lead to deadlock</title>
<para>
   </para><para>

   One of the work items currently on the workqueue needs to acquire
   a lock held by your code or its caller.
   </para><para>

   Your code is running in the context of a work routine.
   </para><para>

   They will be detected by lockdep when they occur, but the first might not
   occur very often.  It depends on what work items are on the workqueue and
   what locks they need, which you have no control over.
   </para><para>

   In most situations flushing the entire workqueue is overkill; you merely
   need to know that a particular work item isn't queued and isn't running.
   In such cases you should use <function><link linkend="API-cancel-delayed-work-sync">cancel_delayed_work_sync</link></function> or
   <function><link linkend="API-cancel-work-sync">cancel_work_sync</link></function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-schedule-delayed-work-on">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>schedule_delayed_work_on</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>schedule_delayed_work_on</refname>
 <refpurpose>
     queue work in global workqueue on CPU after delay
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>schedule_delayed_work_on </function></funcdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
   <paramdef>unsigned long <parameter>delay</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     cpu to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     job to be done
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delay</parameter></term>
   <listitem>
    <para>
     number of jiffies to wait
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   After waiting for a given time this puts a job in the kernel-global
   workqueue on the specified CPU.
</para>
</refsect1>
</refentry>

<refentry id="API-schedule-delayed-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>schedule_delayed_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>schedule_delayed_work</refname>
 <refpurpose>
     put work task in global workqueue after delay
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>schedule_delayed_work </function></funcdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
   <paramdef>unsigned long <parameter>delay</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     job to be done
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delay</parameter></term>
   <listitem>
    <para>
     number of jiffies to wait or 0 for immediate execution
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   After waiting for a given time this puts a job in the kernel-global
   workqueue.
</para>
</refsect1>
</refentry>

<refentry id="API-keventd-up">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>keventd_up</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>keventd_up</refname>
 <refpurpose>
     is workqueue initialized yet?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>keventd_up </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- kernel/workqueue.c -->
<refentry id="API-queue-work-on">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>queue_work_on</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>queue_work_on</refname>
 <refpurpose>
  queue work on specific cpu
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>queue_work_on </function></funcdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     CPU number to execute work on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     work to queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   We queue the work to a specific CPU, the caller must ensure it
   can't go away.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> if <parameter>work</parameter> was already on a queue, <constant>true</constant> otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-queue-delayed-work-on">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>queue_delayed_work_on</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>queue_delayed_work_on</refname>
 <refpurpose>
     queue work on specific CPU after delay
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>queue_delayed_work_on </function></funcdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
   <paramdef>unsigned long <parameter>delay</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     CPU number to execute work on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     work to queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delay</parameter></term>
   <listitem>
    <para>
     number of jiffies to wait before queueing
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> if <parameter>work</parameter> was already on a queue, <constant>true</constant> otherwise.  If
   <parameter>delay</parameter> is zero and <parameter>dwork</parameter> is idle, it will be scheduled for immediate
   execution.
</para>
</refsect1>
</refentry>

<refentry id="API-mod-delayed-work-on">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mod_delayed_work_on</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mod_delayed_work_on</refname>
 <refpurpose>
     modify delay of or queue a delayed work on specific CPU
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>mod_delayed_work_on </function></funcdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
   <paramdef>unsigned long <parameter>delay</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     CPU number to execute work on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     work to queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delay</parameter></term>
   <listitem>
    <para>
     number of jiffies to wait before queueing
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If <parameter>dwork</parameter> is idle, equivalent to <function><link linkend="API-queue-delayed-work-on">queue_delayed_work_on</link></function>; otherwise,
   modify <parameter>dwork</parameter>'s timer so that it expires after <parameter>delay</parameter>.  If <parameter>delay</parameter> is
   zero, <parameter>work</parameter> is guaranteed to be scheduled immediately regardless of its
   current state.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> if <parameter>dwork</parameter> was idle and queued, <constant>true</constant> if <parameter>dwork</parameter> was
   pending and its timer was modified.
   </para><para>

   This function is safe to call from any context including IRQ handler.
   See <function>try_to_grab_pending</function> for details.
</para>
</refsect1>
</refentry>

<refentry id="API-flush-workqueue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>flush_workqueue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>flush_workqueue</refname>
 <refpurpose>
     ensure that any scheduled work has run to completion.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>flush_workqueue </function></funcdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to flush
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function sleeps until all work items which were queued on entry
   have finished execution, but it is not livelocked by new incoming ones.
</para>
</refsect1>
</refentry>

<refentry id="API-drain-workqueue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drain_workqueue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drain_workqueue</refname>
 <refpurpose>
     drain a workqueue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drain_workqueue </function></funcdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to drain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Wait until the workqueue becomes empty.  While draining is in progress,
   only chain queueing is allowed.  IOW, only currently pending or running
   work items on <parameter>wq</parameter> can queue further work items on it.  <parameter>wq</parameter> is flushed
   repeatedly until it becomes empty.  The number of flushing is determined
   by the depth of chaining and should be relatively short.  Whine if it
   takes too long.
</para>
</refsect1>
</refentry>

<refentry id="API-flush-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>flush_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>flush_work</refname>
 <refpurpose>
     wait for a work to finish executing the last queueing instance
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>flush_work </function></funcdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     the work to flush
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Wait until <parameter>work</parameter> has finished execution.  <parameter>work</parameter> is guaranteed to be idle
   on return if it hasn't been requeued since flush started.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>true</constant> if <function><link linkend="API-flush-work">flush_work</link></function> waited for the work to finish execution,
   <constant>false</constant> if it was already idle.
</para>
</refsect1>
</refentry>

<refentry id="API-cancel-work-sync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cancel_work_sync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cancel_work_sync</refname>
 <refpurpose>
     cancel a work and wait for it to finish
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>cancel_work_sync </function></funcdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     the work to cancel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Cancel <parameter>work</parameter> and wait for its execution to finish.  This function
   can be used even if the work re-queues itself or migrates to
   another workqueue.  On return from this function, <parameter>work</parameter> is
   guaranteed to be not pending or executing on any CPU.
   </para><para>

   cancel_work_sync(<structname>delayed_work</structname>-&gt;work) must not be used for
   delayed_work's.  Use <function><link linkend="API-cancel-delayed-work-sync">cancel_delayed_work_sync</link></function> instead.
   </para><para>

   The caller must ensure that the workqueue on which <parameter>work</parameter> was last
   queued can't be destroyed before this function returns.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>true</constant> if <parameter>work</parameter> was pending, <constant>false</constant> otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-flush-delayed-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>flush_delayed_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>flush_delayed_work</refname>
 <refpurpose>
     wait for a dwork to finish executing the last queueing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>flush_delayed_work </function></funcdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     the delayed work to flush
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Delayed timer is cancelled and the pending work is queued for
   immediate execution.  Like <function><link linkend="API-flush-work">flush_work</link></function>, this function only
   considers the last queueing instance of <parameter>dwork</parameter>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>true</constant> if <function><link linkend="API-flush-work">flush_work</link></function> waited for the work to finish execution,
   <constant>false</constant> if it was already idle.
</para>
</refsect1>
</refentry>

<refentry id="API-cancel-delayed-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cancel_delayed_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cancel_delayed_work</refname>
 <refpurpose>
     cancel a delayed work
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>cancel_delayed_work </function></funcdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     delayed_work to cancel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Kill off a pending delayed_work.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>true</constant> if <parameter>dwork</parameter> was pending and canceled; <constant>false</constant> if it wasn't
   pending.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   The work callback function may still be running on return, unless
   it returns <constant>true</constant> and the work doesn't re-arm itself.  Explicitly flush or
   use <function><link linkend="API-cancel-delayed-work-sync">cancel_delayed_work_sync</link></function> to wait on it.
   </para><para>

   This function is safe to call from any context including IRQ handler.
</para>
</refsect1>
</refentry>

<refentry id="API-cancel-delayed-work-sync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cancel_delayed_work_sync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cancel_delayed_work_sync</refname>
 <refpurpose>
     cancel a delayed work and wait for it to finish
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>cancel_delayed_work_sync </function></funcdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     the delayed work cancel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is <function><link linkend="API-cancel-work-sync">cancel_work_sync</link></function> for delayed works.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>true</constant> if <parameter>dwork</parameter> was pending, <constant>false</constant> otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-execute-in-process-context">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>execute_in_process_context</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>execute_in_process_context</refname>
 <refpurpose>
     reliably execute the routine with user context
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>execute_in_process_context </function></funcdef>
   <paramdef>work_func_t <parameter>fn</parameter></paramdef>
   <paramdef>struct execute_work * <parameter>ew</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     the function to execute
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ew</parameter></term>
   <listitem>
    <para>
     guaranteed storage for the execute work structure (must
     be available when the work executes)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Executes the function immediately if process context is available,
   otherwise schedules the function for delayed execution.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 - function was executed
   1 - function was scheduled for execution
</para>
</refsect1>
</refentry>

<refentry id="API-destroy-workqueue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>destroy_workqueue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>destroy_workqueue</refname>
 <refpurpose>
     safely terminate a workqueue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>destroy_workqueue </function></funcdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     target workqueue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Safely destroy a workqueue. All work currently pending will be done first.
</para>
</refsect1>
</refentry>

<refentry id="API-workqueue-set-max-active">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>workqueue_set_max_active</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>workqueue_set_max_active</refname>
 <refpurpose>
     adjust max_active of a workqueue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>workqueue_set_max_active </function></funcdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
   <paramdef>int <parameter>max_active</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     target workqueue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_active</parameter></term>
   <listitem>
    <para>
     new max_active value.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set max_active of <parameter>wq</parameter> to <parameter>max_active</parameter>.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Don't call from IRQ context.
</para>
</refsect1>
</refentry>

<refentry id="API-workqueue-congested">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>workqueue_congested</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>workqueue_congested</refname>
 <refpurpose>
     test whether a workqueue is congested
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>workqueue_congested </function></funcdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     CPU in question
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     target workqueue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Test whether <parameter>wq</parameter>'s cpu workqueue for <parameter>cpu</parameter> is congested.  There is
   no synchronization around this function and the test result is
   unreliable and only useful as advisory hints or for debugging.
   </para><para>

   If <parameter>cpu</parameter> is WORK_CPU_UNBOUND, the test is performed on the local CPU.
   Note that both per-cpu and unbound workqueues may be associated with
   multiple pool_workqueues which have separate congested states.  A
   workqueue being congested on one CPU doesn't mean the workqueue is also
   contested on other CPUs / NUMA nodes.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>true</constant> if congested, <constant>false</constant> otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-work-busy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>work_busy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>work_busy</refname>
 <refpurpose>
     test whether a work is currently pending or running
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>work_busy </function></funcdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     the work to be tested
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Test whether <parameter>work</parameter> is currently pending or running.  There is no
   synchronization around this function and the test result is
   unreliable and only useful as advisory hints or for debugging.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   OR'd bitmask of WORK_BUSY_* bits.
</para>
</refsect1>
</refentry>

<refentry id="API-work-on-cpu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>work_on_cpu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>work_on_cpu</refname>
 <refpurpose>
     run a function in user context on a particular cpu
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>work_on_cpu </function></funcdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
   <paramdef>long (*<parameter>fn</parameter>)
     <funcparams>void *</funcparams></paramdef>
   <paramdef>void * <parameter>arg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     the cpu to run on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     the function to run
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>arg</parameter></term>
   <listitem>
    <para>
     the function arg
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It is up to the caller to ensure that the cpu doesn't go offline.
   The caller must not hold any locks which would prevent <parameter>fn</parameter> from completing.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The value <parameter>fn</parameter> returns.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Internal Functions</title>
<!-- kernel/exit.c -->
<refentry id="API-wait-task-stopped">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_task_stopped</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_task_stopped</refname>
 <refpurpose>
  Wait for <constant>TASK_STOPPED</constant> or <constant>TASK_TRACED</constant>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>wait_task_stopped </function></funcdef>
   <paramdef>struct wait_opts * <parameter>wo</parameter></paramdef>
   <paramdef>int <parameter>ptrace</parameter></paramdef>
   <paramdef>struct task_struct * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wo</parameter></term>
   <listitem>
    <para>
     wait options
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptrace</parameter></term>
   <listitem>
    <para>
     is the wait for ptrace
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     task to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Handle <function>sys_wait4</function> work for <constant>p</constant> in state <constant>TASK_STOPPED</constant> or <constant>TASK_TRACED</constant>.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   read_lock(<structname>tasklist_lock</structname>), which is released if return value is
   non-zero.  Also, grabs and releases <parameter>p</parameter>-&gt;sighand-&gt;siglock.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 if wait condition didn't exist and search for other wait conditions
   should continue.  Non-zero return, -errno on failure and <parameter>p</parameter>'s pid on
   success, implies that tasklist_lock is released and wait condition
   search should terminate.
</para>
</refsect1>
</refentry>

<!-- kernel/signal.c -->
<refentry id="API-task-set-jobctl-pending">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>task_set_jobctl_pending</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>task_set_jobctl_pending</refname>
 <refpurpose>
  set jobctl pending bits
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>task_set_jobctl_pending </function></funcdef>
   <paramdef>struct task_struct * <parameter>task</parameter></paramdef>
   <paramdef>unsigned long <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>task</parameter></term>
   <listitem>
    <para>
     target task
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     pending bits to set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Clear <parameter>mask</parameter> from <parameter>task</parameter>-&gt;jobctl.  <parameter>mask</parameter> must be subset of
   <constant>JOBCTL_PENDING_MASK</constant> | <constant>JOBCTL_STOP_CONSUME</constant> | <constant>JOBCTL_STOP_SIGMASK</constant> |
   <constant>JOBCTL_TRAPPING</constant>.  If stop signo is being set, the existing signo is
   cleared.  If <parameter>task</parameter> is already being killed or exiting, this function
   becomes noop.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Must be called with <parameter>task</parameter>-&gt;sighand-&gt;siglock held.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   <constant>true</constant> if <parameter>mask</parameter> is set, <constant>false</constant> if made noop because <parameter>task</parameter> was dying.
</para>
</refsect1>
</refentry>

<refentry id="API-task-clear-jobctl-trapping">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>task_clear_jobctl_trapping</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>task_clear_jobctl_trapping</refname>
 <refpurpose>
     clear jobctl trapping bit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>task_clear_jobctl_trapping </function></funcdef>
   <paramdef>struct task_struct * <parameter>task</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>task</parameter></term>
   <listitem>
    <para>
     target task
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If JOBCTL_TRAPPING is set, a ptracer is waiting for us to enter TRACED.
   Clear it and wake up the ptracer.  Note that we don't need any further
   locking.  <parameter>task</parameter>-&gt;siglock guarantees that <parameter>task</parameter>-&gt;parent points to the
   ptracer.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Must be called with <parameter>task</parameter>-&gt;sighand-&gt;siglock held.
</para>
</refsect1>
</refentry>

<refentry id="API-task-clear-jobctl-pending">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>task_clear_jobctl_pending</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>task_clear_jobctl_pending</refname>
 <refpurpose>
     clear jobctl pending bits
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>task_clear_jobctl_pending </function></funcdef>
   <paramdef>struct task_struct * <parameter>task</parameter></paramdef>
   <paramdef>unsigned long <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>task</parameter></term>
   <listitem>
    <para>
     target task
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     pending bits to clear
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Clear <parameter>mask</parameter> from <parameter>task</parameter>-&gt;jobctl.  <parameter>mask</parameter> must be subset of
   <constant>JOBCTL_PENDING_MASK</constant>.  If <constant>JOBCTL_STOP_PENDING</constant> is being cleared, other
   STOP bits are cleared together.
   </para><para>

   If clearing of <parameter>mask</parameter> leaves no stop or trap pending, this function calls
   <function><link linkend="API-task-clear-jobctl-trapping">task_clear_jobctl_trapping</link></function>.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Must be called with <parameter>task</parameter>-&gt;sighand-&gt;siglock held.
</para>
</refsect1>
</refentry>

<refentry id="API-task-participate-group-stop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>task_participate_group_stop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>task_participate_group_stop</refname>
 <refpurpose>
     participate in a group stop
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>task_participate_group_stop </function></funcdef>
   <paramdef>struct task_struct * <parameter>task</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>task</parameter></term>
   <listitem>
    <para>
     task participating in a group stop
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <parameter>task</parameter> has <constant>JOBCTL_STOP_PENDING</constant> set and is participating in a group stop.
   Group stop states are cleared and the group stop count is consumed if
   <constant>JOBCTL_STOP_CONSUME</constant> was set.  If the consumption completes the group
   stop, the appropriate <constant>SIGNAL_</constant>* flags are set.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Must be called with <parameter>task</parameter>-&gt;sighand-&gt;siglock held.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   <constant>true</constant> if group stop completion should be notified to the parent, <constant>false</constant>
   otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-ptrace-trap-notify">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ptrace_trap_notify</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ptrace_trap_notify</refname>
 <refpurpose>
     schedule trap to notify ptracer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ptrace_trap_notify </function></funcdef>
   <paramdef>struct task_struct * <parameter>t</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>t</parameter></term>
   <listitem>
    <para>
     tracee wanting to notify tracer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function schedules sticky ptrace trap which is cleared on the next
   TRAP_STOP to notify ptracer of an event.  <parameter>t</parameter> must have been seized by
   ptracer.
   </para><para>

   If <parameter>t</parameter> is running, STOP trap will be taken.  If trapped for STOP and
   ptracer is listening for events, tracee is woken up so that it can
   re-trap for the new event.  If trapped otherwise, STOP trap will be
   eventually taken without returning to userland after the existing traps
   are finished by PTRACE_CONT.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Must be called with <parameter>task</parameter>-&gt;sighand-&gt;siglock held.
</para>
</refsect1>
</refentry>

<refentry id="API-do-notify-parent-cldstop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>do_notify_parent_cldstop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>do_notify_parent_cldstop</refname>
 <refpurpose>
     notify parent of stopped/continued state change
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>do_notify_parent_cldstop </function></funcdef>
   <paramdef>struct task_struct * <parameter>tsk</parameter></paramdef>
   <paramdef>bool <parameter>for_ptracer</parameter></paramdef>
   <paramdef>int <parameter>why</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>tsk</parameter></term>
   <listitem>
    <para>
     task reporting the state change
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>for_ptracer</parameter></term>
   <listitem>
    <para>
     the notification is for ptracer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>why</parameter></term>
   <listitem>
    <para>
     CLD_{CONTINUED|STOPPED|TRAPPED} to report
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Notify <parameter>tsk</parameter>'s parent that the stopped/continued state has changed.  If
   <parameter>for_ptracer</parameter> is <constant>false</constant>, <parameter>tsk</parameter>'s group leader notifies to its real parent.
   If <constant>true</constant>, <parameter>tsk</parameter> reports to <parameter>tsk</parameter>-&gt;parent which should be the ptracer.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Must be called with tasklist_lock at least read locked.
</para>
</refsect1>
</refentry>

<refentry id="API-do-signal-stop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>do_signal_stop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>do_signal_stop</refname>
 <refpurpose>
     handle group stop for SIGSTOP and other stop signals
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>do_signal_stop </function></funcdef>
   <paramdef>int <parameter>signr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>signr</parameter></term>
   <listitem>
    <para>
     signr causing group stop if initiating
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If <constant>JOBCTL_STOP_PENDING</constant> is not set yet, initiate group stop with <parameter>signr</parameter>
   and participate in it.  If already set, participate in the existing
   group stop.  If participated in a group stop (and thus slept), <constant>true</constant> is
   returned with siglock released.
   </para><para>

   If ptraced, this function doesn't handle stop itself.  Instead,
   <constant>JOBCTL_TRAP_STOP</constant> is scheduled and <constant>false</constant> is returned with siglock
   untouched.  The caller must ensure that INTERRUPT trap handling takes
   places afterwards.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Must be called with <parameter>current</parameter>-&gt;sighand-&gt;siglock held, which is released
   on <constant>true</constant> return.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   <constant>false</constant> if group stop is already cancelled or ptrace trap is scheduled.
   <constant>true</constant> if participated in group stop.
</para>
</refsect1>
</refentry>

<refentry id="API-do-jobctl-trap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>do_jobctl_trap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>do_jobctl_trap</refname>
 <refpurpose>
     take care of ptrace jobctl traps
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>do_jobctl_trap </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   When PT_SEIZED, it's used for both group stop and explicit
   SEIZE/INTERRUPT traps.  Both generate PTRACE_EVENT_STOP trap with
   accompanying siginfo.  If stopped, lower eight bits of exit_code contain
   the stop signal; otherwise, <constant>SIGTRAP</constant>.
   </para><para>

   When !PT_SEIZED, it's used only for group stop trap with stop signal
   number as exit_code and no siginfo.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Must be called with <parameter>current</parameter>-&gt;sighand-&gt;siglock held, which may be
   released and re-acquired before returning with intervening sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-signal-delivered">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>signal_delivered</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>signal_delivered</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>signal_delivered </function></funcdef>
   <paramdef>struct ksignal * <parameter>ksig</parameter></paramdef>
   <paramdef>int <parameter>stepping</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ksig</parameter></term>
   <listitem>
    <para>
     kernel signal struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>stepping</parameter></term>
   <listitem>
    <para>
     nonzero if debugger single-step or block-step in use
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should be called when a signal has successfully been
   delivered. It updates the blocked signals accordingly (<parameter>ksig</parameter>-&gt;ka.sa.sa_mask
   is always blocked, and the signal itself is blocked unless <constant>SA_NODEFER</constant>
   is set in <parameter>ksig</parameter>-&gt;ka.sa.sa_flags.  Tracing is notified.
</para>
</refsect1>
</refentry>

<refentry id="API-sys-restart-syscall">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_restart_syscall</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_restart_syscall</refname>
 <refpurpose>
     restart a system call
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_restart_syscall </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-set-current-blocked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>set_current_blocked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>set_current_blocked</refname>
 <refpurpose>
     change current-&gt;blocked mask
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>set_current_blocked </function></funcdef>
   <paramdef>sigset_t * <parameter>newset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>newset</parameter></term>
   <listitem>
    <para>
     new mask
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It is wrong to change -&gt;blocked directly, this helper should be used
   to ensure the process can't miss a shared signal we are going to block.
</para>
</refsect1>
</refentry>

<refentry id="API-sys-rt-sigprocmask">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_rt_sigprocmask</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_rt_sigprocmask</refname>
 <refpurpose>
     change the list of currently blocked signals
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_rt_sigprocmask </function></funcdef>
   <paramdef>int <parameter>how</parameter></paramdef>
   <paramdef>sigset_t __user * <parameter>nset</parameter></paramdef>
   <paramdef>sigset_t __user * <parameter>oset</parameter></paramdef>
   <paramdef>size_t <parameter>sigsetsize</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>how</parameter></term>
   <listitem>
    <para>
     whether to add, remove, or set signals
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nset</parameter></term>
   <listitem>
    <para>
     stores pending signals
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>oset</parameter></term>
   <listitem>
    <para>
     previous value of signal mask if non-null
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sigsetsize</parameter></term>
   <listitem>
    <para>
     size of sigset_t type
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-sys-rt-sigpending">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_rt_sigpending</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_rt_sigpending</refname>
 <refpurpose>
     examine a pending signal that has been raised while blocked
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_rt_sigpending </function></funcdef>
   <paramdef>sigset_t __user * <parameter>uset</parameter></paramdef>
   <paramdef>size_t <parameter>sigsetsize</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>uset</parameter></term>
   <listitem>
    <para>
     stores pending signals
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sigsetsize</parameter></term>
   <listitem>
    <para>
     size of sigset_t type or larger
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-do-sigtimedwait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>do_sigtimedwait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>do_sigtimedwait</refname>
 <refpurpose>
     wait for queued signals specified in <parameter>which</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>do_sigtimedwait </function></funcdef>
   <paramdef>const sigset_t * <parameter>which</parameter></paramdef>
   <paramdef>siginfo_t * <parameter>info</parameter></paramdef>
   <paramdef>const struct timespec * <parameter>ts</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>which</parameter></term>
   <listitem>
    <para>
     queued signals to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     if non-null, the signal's siginfo is returned here
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ts</parameter></term>
   <listitem>
    <para>
     upper bound on process time suspension
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-sys-rt-sigtimedwait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_rt_sigtimedwait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_rt_sigtimedwait</refname>
 <refpurpose>
     synchronously wait for queued signals specified in <parameter>uthese</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_rt_sigtimedwait </function></funcdef>
   <paramdef>const sigset_t __user * <parameter>uthese</parameter></paramdef>
   <paramdef>siginfo_t __user * <parameter>uinfo</parameter></paramdef>
   <paramdef>const struct timespec __user * <parameter>uts</parameter></paramdef>
   <paramdef>size_t <parameter>sigsetsize</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>uthese</parameter></term>
   <listitem>
    <para>
     queued signals to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uinfo</parameter></term>
   <listitem>
    <para>
     if non-null, the signal's siginfo is returned here
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uts</parameter></term>
   <listitem>
    <para>
     upper bound on process time suspension
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sigsetsize</parameter></term>
   <listitem>
    <para>
     size of sigset_t type
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-sys-kill">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_kill</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_kill</refname>
 <refpurpose>
     send a signal to a process
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_kill </function></funcdef>
   <paramdef>pid_t <parameter>pid</parameter></paramdef>
   <paramdef>int <parameter>sig</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pid</parameter></term>
   <listitem>
    <para>
     the PID of the process
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sig</parameter></term>
   <listitem>
    <para>
     signal to be sent
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-sys-tgkill">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_tgkill</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_tgkill</refname>
 <refpurpose>
     send signal to one specific thread
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_tgkill </function></funcdef>
   <paramdef>pid_t <parameter>tgid</parameter></paramdef>
   <paramdef>pid_t <parameter>pid</parameter></paramdef>
   <paramdef>int <parameter>sig</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>tgid</parameter></term>
   <listitem>
    <para>
     the thread group ID of the thread
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pid</parameter></term>
   <listitem>
    <para>
     the PID of the thread
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sig</parameter></term>
   <listitem>
    <para>
     signal to be sent
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This syscall also checks the <parameter>tgid</parameter> and returns -ESRCH even if the PID
   exists but it's not belonging to the target process anymore. This
   method solves the problem of threads exiting and PIDs getting reused.
</para>
</refsect1>
</refentry>

<refentry id="API-sys-tkill">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_tkill</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_tkill</refname>
 <refpurpose>
     send signal to one specific task
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_tkill </function></funcdef>
   <paramdef>pid_t <parameter>pid</parameter></paramdef>
   <paramdef>int <parameter>sig</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pid</parameter></term>
   <listitem>
    <para>
     the PID of the task
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sig</parameter></term>
   <listitem>
    <para>
     signal to be sent
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send a signal to only one task, even if it's a CLONE_THREAD task.
</para>
</refsect1>
</refentry>

<refentry id="API-sys-rt-sigqueueinfo">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_rt_sigqueueinfo</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_rt_sigqueueinfo</refname>
 <refpurpose>
     send signal information to a signal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_rt_sigqueueinfo </function></funcdef>
   <paramdef>pid_t <parameter>pid</parameter></paramdef>
   <paramdef>int <parameter>sig</parameter></paramdef>
   <paramdef>siginfo_t __user * <parameter>uinfo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pid</parameter></term>
   <listitem>
    <para>
     the PID of the thread
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sig</parameter></term>
   <listitem>
    <para>
     signal to be sent
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uinfo</parameter></term>
   <listitem>
    <para>
     signal info to be sent
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-sys-sigpending">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_sigpending</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_sigpending</refname>
 <refpurpose>
     examine pending signals
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_sigpending </function></funcdef>
   <paramdef>old_sigset_t __user * <parameter>set</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>set</parameter></term>
   <listitem>
    <para>
     where mask of pending signal is returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-sys-sigprocmask">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_sigprocmask</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_sigprocmask</refname>
 <refpurpose>
     examine and change blocked signals
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_sigprocmask </function></funcdef>
   <paramdef>int <parameter>how</parameter></paramdef>
   <paramdef>old_sigset_t __user * <parameter>nset</parameter></paramdef>
   <paramdef>old_sigset_t __user * <parameter>oset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>how</parameter></term>
   <listitem>
    <para>
     whether to add, remove, or set signals
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nset</parameter></term>
   <listitem>
    <para>
     signals to add or remove (if non-null)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>oset</parameter></term>
   <listitem>
    <para>
     previous value of signal mask if non-null
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Some platforms have their own version with special arguments;
   others support only sys_rt_sigprocmask.
</para>
</refsect1>
</refentry>

<refentry id="API-sys-rt-sigaction">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_rt_sigaction</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_rt_sigaction</refname>
 <refpurpose>
     alter an action taken by a process
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_rt_sigaction </function></funcdef>
   <paramdef>int <parameter>sig</parameter></paramdef>
   <paramdef>const struct sigaction __user * <parameter>act</parameter></paramdef>
   <paramdef>struct sigaction __user * <parameter>oact</parameter></paramdef>
   <paramdef>size_t <parameter>sigsetsize</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sig</parameter></term>
   <listitem>
    <para>
     signal to be sent
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>act</parameter></term>
   <listitem>
    <para>
     new sigaction
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>oact</parameter></term>
   <listitem>
    <para>
     used to save the previous sigaction
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sigsetsize</parameter></term>
   <listitem>
    <para>
     size of sigset_t type
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-sys-rt-sigsuspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_rt_sigsuspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_rt_sigsuspend</refname>
 <refpurpose>
     replace the signal mask for a value with the <parameter>unewset</parameter> value until a signal is received
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_rt_sigsuspend </function></funcdef>
   <paramdef>sigset_t __user * <parameter>unewset</parameter></paramdef>
   <paramdef>size_t <parameter>sigsetsize</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>unewset</parameter></term>
   <listitem>
    <para>
     new signal mask value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sigsetsize</parameter></term>
   <listitem>
    <para>
     size of sigset_t type
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- include/linux/kthread.h -->
<refentry id="API-kthread-run">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_run</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_run</refname>
 <refpurpose>
  create and wake a thread.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kthread_run </function></funcdef>
   <paramdef> <parameter>threadfn</parameter></paramdef>
   <paramdef> <parameter>data</parameter></paramdef>
   <paramdef> <parameter>namefmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>threadfn</parameter></term>
   <listitem>
    <para>
     the function to run until signal_pending(current).
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data ptr for <parameter>threadfn</parameter>.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>namefmt</parameter></term>
   <listitem>
    <para>
     printf-style name for the thread.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Convenient wrapper for <function>kthread_create</function> followed by
   <function><link linkend="API-wake-up-process">wake_up_process</link></function>.  Returns the kthread or ERR_PTR(-ENOMEM).
</para>
</refsect1>
</refentry>

<!-- kernel/kthread.c -->
<refentry id="API-kthread-should-stop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_should_stop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_should_stop</refname>
 <refpurpose>
  should this kthread return now?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>kthread_should_stop </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   When someone calls <function><link linkend="API-kthread-stop">kthread_stop</link></function> on your kthread, it will be woken
   and this will return true.  You should then return, and your return
   value will be passed through to <function><link linkend="API-kthread-stop">kthread_stop</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-kthread-should-park">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_should_park</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_should_park</refname>
 <refpurpose>
     should this kthread park now?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>kthread_should_park </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   When someone calls <function><link linkend="API-kthread-park">kthread_park</link></function> on your kthread, it will be woken
   and this will return true.  You should then do the necessary
   cleanup and call <function>kthread_parkme</function>
   </para><para>

   Similar to <function><link linkend="API-kthread-should-stop">kthread_should_stop</link></function>, but this keeps the thread alive
   and in a park position. <function><link linkend="API-kthread-unpark">kthread_unpark</link></function> <quote>restarts</quote> the thread and
   calls the thread function again.
</para>
</refsect1>
</refentry>

<refentry id="API-kthread-freezable-should-stop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_freezable_should_stop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_freezable_should_stop</refname>
 <refpurpose>
     should this freezable kthread return now?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>kthread_freezable_should_stop </function></funcdef>
   <paramdef>bool * <parameter>was_frozen</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>was_frozen</parameter></term>
   <listitem>
    <para>
     optional out parameter, indicates whether <constant>current</constant> was frozen
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API-kthread-should-stop">kthread_should_stop</link></function> for freezable kthreads, which will enter
   refrigerator if necessary.  This function is safe from <function><link linkend="API-kthread-stop">kthread_stop</link></function> /
   freezer deadlock and freezable kthreads should use this function instead
   of calling <function>try_to_freeze</function> directly.
</para>
</refsect1>
</refentry>

<refentry id="API-kthread-create-on-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_create_on_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_create_on_node</refname>
 <refpurpose>
     create a kthread.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct task_struct * <function>kthread_create_on_node </function></funcdef>
   <paramdef>int (*<parameter>threadfn</parameter>)
     <funcparams>void *data</funcparams></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int <parameter>node</parameter></paramdef>
   <paramdef>const char <parameter>namefmt[]</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>threadfn</parameter></term>
   <listitem>
    <para>
     the function to run until signal_pending(current).
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data ptr for <parameter>threadfn</parameter>.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     task and thread structures for the thread are allocated on this node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>namefmt[]</parameter></term>
   <listitem>
    <para>
     printf-style name for the thread.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This helper function creates and names a kernel
   thread.  The thread will be stopped: use <function><link linkend="API-wake-up-process">wake_up_process</link></function> to start
   it.  See also <function><link linkend="API-kthread-run">kthread_run</link></function>.  The new thread has SCHED_NORMAL policy and
   is affine to all CPUs.
   </para><para>

   If thread is going to be bound on a particular cpu, give its node
   in <parameter>node</parameter>, to get NUMA affinity for kthread stack, or else give NUMA_NO_NODE.
   When woken, the thread will run <parameter>threadfn</parameter>() with <parameter>data</parameter> as its
   argument. <parameter>threadfn</parameter>() can either call <function>do_exit</function> directly if it is a
   standalone thread for which no one will call <function><link linkend="API-kthread-stop">kthread_stop</link></function>, or
   return when '<function><link linkend="API-kthread-should-stop">kthread_should_stop</link></function>' is true (which means
   <function><link linkend="API-kthread-stop">kthread_stop</link></function> has been called).  The return value should be zero
   or a negative error number; it will be passed to <function><link linkend="API-kthread-stop">kthread_stop</link></function>.
   </para><para>

   Returns a task_struct or ERR_PTR(-ENOMEM) or ERR_PTR(-EINTR).
</para>
</refsect1>
</refentry>

<refentry id="API-kthread-bind">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_bind</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_bind</refname>
 <refpurpose>
     bind a just-created kthread to a cpu.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kthread_bind </function></funcdef>
   <paramdef>struct task_struct * <parameter>p</parameter></paramdef>
   <paramdef>unsigned int <parameter>cpu</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     thread created by <function>kthread_create</function>.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     cpu (might not be online, must be possible) for <parameter>k</parameter> to run on.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is equivalent to <function>set_cpus_allowed</function>,
   except that <parameter>cpu</parameter> doesn't need to be online, and the thread must be
   stopped (i.e., just returned from <function>kthread_create</function>).
</para>
</refsect1>
</refentry>

<refentry id="API-kthread-unpark">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_unpark</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_unpark</refname>
 <refpurpose>
     unpark a thread created by <function>kthread_create</function>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kthread_unpark </function></funcdef>
   <paramdef>struct task_struct * <parameter>k</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>k</parameter></term>
   <listitem>
    <para>
     thread created by <function>kthread_create</function>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets <function><link linkend="API-kthread-should-park">kthread_should_park</link></function> for <parameter>k</parameter> to return false, wakes it, and
   waits for it to return. If the thread is marked percpu then its
   bound to the cpu again.
</para>
</refsect1>
</refentry>

<refentry id="API-kthread-park">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_park</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_park</refname>
 <refpurpose>
     park a thread created by <function>kthread_create</function>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kthread_park </function></funcdef>
   <paramdef>struct task_struct * <parameter>k</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>k</parameter></term>
   <listitem>
    <para>
     thread created by <function>kthread_create</function>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets <function><link linkend="API-kthread-should-park">kthread_should_park</link></function> for <parameter>k</parameter> to return true, wakes it, and
   waits for it to return. This can also be called after <function>kthread_create</function>
   instead of calling <function><link linkend="API-wake-up-process">wake_up_process</link></function>: the thread will park without
   calling <function>threadfn</function>.
   </para><para>

   Returns 0 if the thread is parked, -ENOSYS if the thread exited.
   If called by the kthread itself just the park bit is set.
</para>
</refsect1>
</refentry>

<refentry id="API-kthread-stop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_stop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_stop</refname>
 <refpurpose>
     stop a thread created by <function>kthread_create</function>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kthread_stop </function></funcdef>
   <paramdef>struct task_struct * <parameter>k</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>k</parameter></term>
   <listitem>
    <para>
     thread created by <function>kthread_create</function>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets <function><link linkend="API-kthread-should-stop">kthread_should_stop</link></function> for <parameter>k</parameter> to return true, wakes it, and
   waits for it to exit. This can also be called after <function>kthread_create</function>
   instead of calling <function><link linkend="API-wake-up-process">wake_up_process</link></function>: the thread will exit without
   calling <function>threadfn</function>.
   </para><para>

   If <function>threadfn</function> may call <function>do_exit</function> itself, the caller must ensure
   task_struct can't go away.
   </para><para>

   Returns the result of <function>threadfn</function>, or <constant>-EINTR</constant> if <function><link linkend="API-wake-up-process">wake_up_process</link></function>
   was never called.
</para>
</refsect1>
</refentry>

<refentry id="API-kthread-worker-fn">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_worker_fn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_worker_fn</refname>
 <refpurpose>
     kthread function to process kthread_worker
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kthread_worker_fn </function></funcdef>
   <paramdef>void * <parameter>worker_ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>worker_ptr</parameter></term>
   <listitem>
    <para>
     pointer to initialized kthread_worker
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can be used as <parameter>threadfn</parameter> to <function>kthread_create</function> or
   <function><link linkend="API-kthread-run">kthread_run</link></function> with <parameter>worker_ptr</parameter> argument pointing to an initialized
   kthread_worker.  The started kthread will process work_list until
   the it is stopped with <function><link linkend="API-kthread-stop">kthread_stop</link></function>.  A kthread can also call
   this function directly after extra initialization.
   </para><para>

   Different kthreads can be used for the same kthread_worker as long
   as there's only one kthread attached to it at any given time.  A
   kthread_worker without an attached kthread simply collects queued
   kthread_works.
</para>
</refsect1>
</refentry>

<refentry id="API-queue-kthread-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>queue_kthread_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>queue_kthread_work</refname>
 <refpurpose>
     queue a kthread_work
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>queue_kthread_work </function></funcdef>
   <paramdef>struct kthread_worker * <parameter>worker</parameter></paramdef>
   <paramdef>struct kthread_work * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>worker</parameter></term>
   <listitem>
    <para>
     target kthread_worker
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     kthread_work to queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Queue <parameter>work</parameter> to work processor <parameter>task</parameter> for async execution.  <parameter>task</parameter>
   must have been created with <function>kthread_worker_create</function>.  Returns <constant>true</constant>
   if <parameter>work</parameter> was successfully queued, <constant>false</constant> if it was already pending.
</para>
</refsect1>
</refentry>

<refentry id="API-flush-kthread-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>flush_kthread_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>flush_kthread_work</refname>
 <refpurpose>
     flush a kthread_work
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>flush_kthread_work </function></funcdef>
   <paramdef>struct kthread_work * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     work to flush
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If <parameter>work</parameter> is queued or executing, wait for it to finish execution.
</para>
</refsect1>
</refentry>

<refentry id="API-flush-kthread-worker">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>flush_kthread_worker</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>flush_kthread_worker</refname>
 <refpurpose>
     flush all current works on a kthread_worker
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>flush_kthread_worker </function></funcdef>
   <paramdef>struct kthread_worker * <parameter>worker</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>worker</parameter></term>
   <listitem>
    <para>
     worker to flush
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Wait until all currently executing or pending works on <parameter>worker</parameter> are
   finished.
</para>
</refsect1>
</refentry>

     </sect1>

     <sect1><title>Kernel objects manipulation</title>
<!--
X!Iinclude/linux/kobject.h
-->
<!-- lib/kobject.c -->
<refentry id="API-kobject-get-path">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_get_path</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_get_path</refname>
 <refpurpose>
  generate and return the path associated with a given kobj and kset pair.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>kobject_get_path </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     kobject in question, with which to build the path
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     the allocation type used to allocate the path
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The result must be freed by the caller with <function>kfree</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-kobject-set-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_set_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_set_name</refname>
 <refpurpose>
     Set the name of a kobject
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kobject_set_name </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     struct kobject to set the name of
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string used to build the name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This sets the name of the kobject.  If you have already added the
   kobject to the system, you must call <function><link linkend="API-kobject-rename">kobject_rename</link></function> in order to
   change the name of the kobject.
</para>
</refsect1>
</refentry>

<refentry id="API-kobject-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_init</refname>
 <refpurpose>
     initialize a kobject structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kobject_init </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>struct kobj_type * <parameter>ktype</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     pointer to the kobject to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ktype</parameter></term>
   <listitem>
    <para>
     pointer to the ktype for this kobject.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will properly initialize a kobject such that it can then
   be passed to the <function><link linkend="API-kobject-add">kobject_add</link></function> call.
   </para><para>

   After this function is called, the kobject MUST be cleaned up by a call
   to <function><link linkend="API-kobject-put">kobject_put</link></function>, not by a call to kfree directly to ensure that all of
   the memory is cleaned up properly.
</para>
</refsect1>
</refentry>

<refentry id="API-kobject-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_add</refname>
 <refpurpose>
     the main kobject add function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kobject_add </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>struct kobject * <parameter>parent</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     the kobject to add
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     pointer to the parent of the kobject.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format to name the kobject with.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The kobject name is set and added to the kobject hierarchy in this
   function.
   </para><para>

   If <parameter>parent</parameter> is set, then the parent of the <parameter>kobj</parameter> will be set to it.
   If <parameter>parent</parameter> is NULL, then the parent of the <parameter>kobj</parameter> will be set to the
   kobject associated with the kset assigned to this kobject.  If no kset
   is assigned to the kobject, then the kobject will be located in the
   root of the sysfs tree.
   </para><para>

   If this function returns an error, <function><link linkend="API-kobject-put">kobject_put</link></function> must be called to
   properly clean up the memory associated with the object.
   Under no instance should the kobject that is passed to this function
   be directly freed with a call to <function>kfree</function>, that can leak memory.
   </para><para>

   Note, no <quote>add</quote> uevent will be created with this call, the caller should set
   up all of the necessary sysfs files for the object and then call
   <function>kobject_uevent</function> with the UEVENT_ADD parameter to ensure that
   userspace is properly notified of this kobject's creation.
</para>
</refsect1>
</refentry>

<refentry id="API-kobject-init-and-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_init_and_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_init_and_add</refname>
 <refpurpose>
     initialize a kobject structure and add it to the kobject hierarchy
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kobject_init_and_add </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>struct kobj_type * <parameter>ktype</parameter></paramdef>
   <paramdef>struct kobject * <parameter>parent</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     pointer to the kobject to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ktype</parameter></term>
   <listitem>
    <para>
     pointer to the ktype for this kobject.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     pointer to the parent of this kobject.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     the name of the kobject.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function combines the call to <function><link linkend="API-kobject-init">kobject_init</link></function> and
   <function><link linkend="API-kobject-add">kobject_add</link></function>.  The same type of error handling after a call to
   <function><link linkend="API-kobject-add">kobject_add</link></function> and kobject lifetime rules are the same here.
</para>
</refsect1>
</refentry>

<refentry id="API-kobject-rename">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_rename</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_rename</refname>
 <refpurpose>
     change the name of an object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kobject_rename </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>const char * <parameter>new_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     object in question.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_name</parameter></term>
   <listitem>
    <para>
     object's new name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It is the responsibility of the caller to provide mutual
   exclusion between two different calls of kobject_rename
   on the same kobject and to ensure that new_name is valid and
   won't conflict with other kobjects.
</para>
</refsect1>
</refentry>

<refentry id="API-kobject-move">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_move</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_move</refname>
 <refpurpose>
     move object to another parent
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kobject_move </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>struct kobject * <parameter>new_parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     object in question.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_parent</parameter></term>
   <listitem>
    <para>
     object's new parent (can be NULL)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kobject-del">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_del</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_del</refname>
 <refpurpose>
     unlink kobject from hierarchy.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kobject_del </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     object.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kobject-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_get</refname>
 <refpurpose>
     increment refcount for object.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kobject * <function>kobject_get </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     object.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kobject-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_put</refname>
 <refpurpose>
     decrement refcount for object.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kobject_put </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     object.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Decrement the refcount, and if 0, call <function>kobject_cleanup</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-kobject-create-and-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_create_and_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_create_and_add</refname>
 <refpurpose>
     create a struct kobject dynamically and register it with sysfs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kobject * <function>kobject_create_and_add </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct kobject * <parameter>parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the name for the kobject
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     the parent kobject of this kobject, if any.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function creates a kobject structure dynamically and registers it
   with sysfs.  When you are finished with this structure, call
   <function><link linkend="API-kobject-put">kobject_put</link></function> and the structure will be dynamically freed when
   it is no longer being used.
   </para><para>

   If the kobject was not able to be created, NULL will be returned.
</para>
</refsect1>
</refentry>

<refentry id="API-kset-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kset_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kset_register</refname>
 <refpurpose>
     initialize and add a kset.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kset_register </function></funcdef>
   <paramdef>struct kset * <parameter>k</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>k</parameter></term>
   <listitem>
    <para>
     kset.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kset-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kset_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kset_unregister</refname>
 <refpurpose>
     remove a kset.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kset_unregister </function></funcdef>
   <paramdef>struct kset * <parameter>k</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>k</parameter></term>
   <listitem>
    <para>
     kset.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kset-create-and-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kset_create_and_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kset_create_and_add</refname>
 <refpurpose>
     create a struct kset dynamically and add it to sysfs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kset * <function>kset_create_and_add </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>const struct kset_uevent_ops * <parameter>uevent_ops</parameter></paramdef>
   <paramdef>struct kobject * <parameter>parent_kobj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the name for the kset
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uevent_ops</parameter></term>
   <listitem>
    <para>
     a struct kset_uevent_ops for the kset
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent_kobj</parameter></term>
   <listitem>
    <para>
     the parent kobject of this kset, if any.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function creates a kset structure dynamically and registers it
   with sysfs.  When you are finished with this structure, call
   <function><link linkend="API-kset-unregister">kset_unregister</link></function> and the structure will be dynamically freed when it
   is no longer being used.
   </para><para>

   If the kset was not able to be created, NULL will be returned.
</para>
</refsect1>
</refentry>

     </sect1>

     <sect1><title>Kernel utility functions</title>
<!-- include/linux/kernel.h -->
<refentry id="API-upper-32-bits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>upper_32_bits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>upper_32_bits</refname>
 <refpurpose>
  return bits 32-63 of a number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>upper_32_bits </function></funcdef>
   <paramdef> <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     the number we're accessing
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A basic shift-right of a 64- or 32-bit quantity.  Use this to suppress
   the <quote>right shift count &gt;= width of type</quote> warning when that quantity is
   32-bits.
</para>
</refsect1>
</refentry>

<refentry id="API-lower-32-bits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>lower_32_bits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>lower_32_bits</refname>
 <refpurpose>
     return bits 0-31 of a number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>lower_32_bits </function></funcdef>
   <paramdef> <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     the number we're accessing
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-might-sleep">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>might_sleep</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>might_sleep</refname>
 <refpurpose>
     annotation for functions that can sleep
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>might_sleep </function></funcdef>
  <void/>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <para>
  None
 </para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   this macro will print a stack trace if it is executed in an atomic
   context (spinlock, irq-handler, ...).
   </para><para>

   This is a useful debugging help to be able to catch problems early and not
   be bitten later when the calling function happens to sleep when it is not
   supposed to.
</para>
</refsect1>
</refentry>

<refentry id="API-abs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>abs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>abs</refname>
 <refpurpose>
     return absolute value of an argument
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>abs </function></funcdef>
   <paramdef> <parameter>x</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     the value.  If it is unsigned type, it is converted to signed type first
     (s64, long or int depending on its size).
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   an absolute value of x.  If x is 64-bit, macro's return type is s64,
   otherwise it is signed long.
</para>
</refsect1>
</refentry>

<refentry id="API-reciprocal-scale">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>reciprocal_scale</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>reciprocal_scale</refname>
 <refpurpose>
     "scale" a value into range [0, ep_ro)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>reciprocal_scale </function></funcdef>
   <paramdef>u32 <parameter>val</parameter></paramdef>
   <paramdef>u32 <parameter>ep_ro</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ep_ro</parameter></term>
   <listitem>
    <para>
     right open interval endpoint
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Perform a <quote>reciprocal multiplication</quote> in order to <quote>scale</quote> a value into
   range [0, ep_ro), where the upper interval endpoint is right-open.
   This is useful, e.g. for accessing a index of an array containing
   ep_ro elements, for example. Think of it as sort of modulus, only that
   the result isn't that of modulo. ;) Note that if initial input is a
   small value, then result will return 0.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   a result based on val in interval [0, ep_ro).
</para>
</refsect1>
</refentry>

<refentry id="API-kstrtoul">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kstrtoul</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kstrtoul</refname>
 <refpurpose>
     convert a string to an unsigned long
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kstrtoul </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>unsigned int <parameter>base</parameter></paramdef>
   <paramdef>unsigned long * <parameter>res</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The start of the string. The string must be null-terminated, and may also
     include a single newline before its terminating null. The first character
     may also be a plus sign, but not a minus sign.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     The number base to use. The maximum supported base is 16. If base is
     given as 0, then the base of the string is automatically detected with the
     conventional semantics - If it begins with 0x the number will be parsed as a
     hexadecimal (case insensitive), if it otherwise begins with 0, it will be
     parsed as an octal number. Otherwise it will be parsed as a decimal.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     Where to write the result of the conversion on success.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success, -ERANGE on overflow and -EINVAL on parsing error.
   Used as a replacement for the obsolete simple_strtoull. Return code must
   be checked.
</para>
</refsect1>
</refentry>

<refentry id="API-kstrtol">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kstrtol</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kstrtol</refname>
 <refpurpose>
     convert a string to a long
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kstrtol </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>unsigned int <parameter>base</parameter></paramdef>
   <paramdef>long * <parameter>res</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The start of the string. The string must be null-terminated, and may also
     include a single newline before its terminating null. The first character
     may also be a plus sign or a minus sign.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     The number base to use. The maximum supported base is 16. If base is
     given as 0, then the base of the string is automatically detected with the
     conventional semantics - If it begins with 0x the number will be parsed as a
     hexadecimal (case insensitive), if it otherwise begins with 0, it will be
     parsed as an octal number. Otherwise it will be parsed as a decimal.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     Where to write the result of the conversion on success.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success, -ERANGE on overflow and -EINVAL on parsing error.
   Used as a replacement for the obsolete simple_strtoull. Return code must
   be checked.
</para>
</refsect1>
</refentry>

<refentry id="API-trace-printk">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>trace_printk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>trace_printk</refname>
 <refpurpose>
     printf formatting in the ftrace buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>trace_printk </function></funcdef>
   <paramdef> <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     the printf format for printing
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   __trace_printk is an internal function for trace_printk and
   the <parameter>ip</parameter> is passed in via the trace_printk macro.
   </para><para>

   This function allows a kernel developer to debug fast path sections
   that printk is not appropriate for. By scattering in various
   printk like tracing in the code, a developer can quickly see
   where problems are occurring.
   </para><para>

   This is intended as a debugging tool for the developer only.
   Please refrain from leaving trace_printks scattered around in
   your code. (Extra memory is used for special buffers that are
   allocated when <function><link linkend="API-trace-printk">trace_printk</link></function> is used)
   </para><para>

   A little optization trick is done here. If there's only one
   argument, there's no need to scan the string for printf formats.
   The <function><link linkend="API-trace-puts">trace_puts</link></function> will suffice. But how can we take advantage of
   using <function><link linkend="API-trace-puts">trace_puts</link></function> when <function><link linkend="API-trace-printk">trace_printk</link></function> has only one argument?
   By stringifying the args and checking the size we can tell
   whether or not there are args. __stringify((__VA_ARGS__)) will
   turn into <quote>()\0</quote> with a size of 3 when there are no args, anything
   else will be bigger. All we need to do is define a string to this,
   and then take its size and compare to 3. If it's bigger, use
   <function>do_trace_printk</function> otherwise, optimize it to <function><link linkend="API-trace-puts">trace_puts</link></function>. Then just
   let gcc optimize the rest.
</para>
</refsect1>
</refentry>

<refentry id="API-trace-puts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>trace_puts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>trace_puts</refname>
 <refpurpose>
     write a string into the ftrace buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>trace_puts </function></funcdef>
   <paramdef> <parameter>str</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>str</parameter></term>
   <listitem>
    <para>
     the string to record
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   __trace_bputs is an internal function for trace_puts and
   the <parameter>ip</parameter> is passed in via the trace_puts macro.
   </para><para>

   This is similar to <function><link linkend="API-trace-printk">trace_printk</link></function> but is made for those really fast
   paths that a developer wants the least amount of <quote>Heisenbug</quote> affects,
   where the processing of the print format is still too much.
   </para><para>

   This function allows a kernel developer to debug fast path sections
   that printk is not appropriate for. By scattering in various
   printk like tracing in the code, a developer can quickly see
   where problems are occurring.
   </para><para>

   This is intended as a debugging tool for the developer only.
   Please refrain from leaving trace_puts scattered around in
   your code. (Extra memory is used for special buffers that are
   allocated when <function><link linkend="API-trace-puts">trace_puts</link></function> is used)
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 if nothing was written, positive # if string was.
   (1 when __trace_bputs is used, strlen(str) when __trace_puts is used)
</para>
</refsect1>
</refentry>

<refentry id="API-min-not-zero">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>min_not_zero</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>min_not_zero</refname>
 <refpurpose>
     return the minimum that is _not_ zero, unless both are zero
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>min_not_zero </function></funcdef>
   <paramdef> <parameter>x</parameter></paramdef>
   <paramdef> <parameter>y</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     value1
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>y</parameter></term>
   <listitem>
    <para>
     value2
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-clamp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clamp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clamp</refname>
 <refpurpose>
     return a value clamped to a given range with strict typechecking
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>clamp </function></funcdef>
   <paramdef> <parameter>val</parameter></paramdef>
   <paramdef> <parameter>lo</parameter></paramdef>
   <paramdef> <parameter>hi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     current value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lo</parameter></term>
   <listitem>
    <para>
     lowest allowable value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hi</parameter></term>
   <listitem>
    <para>
     highest allowable value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro does strict typechecking of lo/hi to make sure they are of the
   same type as val.  See the unnecessary pointer comparisons.
</para>
</refsect1>
</refentry>

<refentry id="API-clamp-t">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clamp_t</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clamp_t</refname>
 <refpurpose>
     return a value clamped to a given range using a given type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>clamp_t </function></funcdef>
   <paramdef> <parameter>type</parameter></paramdef>
   <paramdef> <parameter>val</parameter></paramdef>
   <paramdef> <parameter>lo</parameter></paramdef>
   <paramdef> <parameter>hi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the type of variable to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     current value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lo</parameter></term>
   <listitem>
    <para>
     minimum allowable value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hi</parameter></term>
   <listitem>
    <para>
     maximum allowable value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro does no typechecking and uses temporary variables of type
   'type' to make all the comparisons.
</para>
</refsect1>
</refentry>

<refentry id="API-clamp-val">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clamp_val</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clamp_val</refname>
 <refpurpose>
     return a value clamped to a given range using val's type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>clamp_val </function></funcdef>
   <paramdef> <parameter>val</parameter></paramdef>
   <paramdef> <parameter>lo</parameter></paramdef>
   <paramdef> <parameter>hi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     current value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lo</parameter></term>
   <listitem>
    <para>
     minimum allowable value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hi</parameter></term>
   <listitem>
    <para>
     maximum allowable value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro does no typechecking and uses temporary variables of whatever
   type the input argument 'val' is.  This is useful when val is an unsigned
   type and min and max are literals that will otherwise be assigned a signed
   integer type.
</para>
</refsect1>
</refentry>

<refentry id="API-container-of">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>container_of</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>container_of</refname>
 <refpurpose>
     cast a member of a structure out to the containing structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>container_of </function></funcdef>
   <paramdef> <parameter>ptr</parameter></paramdef>
   <paramdef> <parameter>type</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     the pointer to the member.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the type of the container struct this is embedded in.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the member within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- kernel/printk/printk.c -->
<refentry id="API-printk">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>printk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>printk</refname>
 <refpurpose>
  print a kernel message
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__visible int <function>printk </function></funcdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is <function><link linkend="API-printk">printk</link></function>. It can be called from any context. We want it to work.
   </para><para>

   We try to grab the console_lock. If we succeed, it's easy - we log the
   output and call the console drivers.  If we fail to get the semaphore, we
   place the output into the log buffer and return. The current holder of
   the console_sem will notice the new output in <function><link linkend="API-console-unlock">console_unlock</link></function>; and will
   send it to the consoles before releasing the lock.
   </para><para>

   One effect of this deferred printing is that code which calls <function><link linkend="API-printk">printk</link></function> and
   then changes console_loglevel may break. This is because console_loglevel
   is inspected when the actual printing occurs.
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>
   printf(3)
   </para><para>

   See the <function>vsnprintf</function> documentation for format string extensions over C99.
</para>
</refsect1>
</refentry>

<refentry id="API-console-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>console_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>console_lock</refname>
 <refpurpose>
     lock the console system for exclusive use.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>console_lock </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Acquires a lock which guarantees that the caller has
   exclusive access to the console system and the console_drivers list.
   </para><para>

   Can sleep, returns nothing.
</para>
</refsect1>
</refentry>

<refentry id="API-console-trylock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>console_trylock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>console_trylock</refname>
 <refpurpose>
     try to lock the console system for exclusive use.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>console_trylock </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Try to acquire a lock which guarantees that the caller has exclusive
   access to the console system and the console_drivers list.
   </para><para>

   returns 1 on success, and 0 on failure to acquire the lock.
</para>
</refsect1>
</refentry>

<refentry id="API-console-unlock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>console_unlock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>console_unlock</refname>
 <refpurpose>
     unlock the console system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>console_unlock </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Releases the console_lock which the caller holds on the console system
   and the console driver list.
   </para><para>

   While the console_lock was held, console output may have been buffered
   by <function><link linkend="API-printk">printk</link></function>.  If this is the case, <function><link linkend="API-console-unlock">console_unlock</link></function>; emits
   the output prior to releasing the lock.
   </para><para>

   If there is output waiting, we wake /dev/kmsg and <function>syslog</function> users.
   </para><para>

   <function><link linkend="API-console-unlock">console_unlock</link></function>; may be called from any context.
</para>
</refsect1>
</refentry>

<refentry id="API-console-conditional-schedule">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>console_conditional_schedule</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>console_conditional_schedule</refname>
 <refpurpose>
     yield the CPU if required
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __sched <function>console_conditional_schedule </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   If the console code is currently allowed to sleep, and
   if this CPU should yield the CPU to another task, do
   so here.
   </para><para>

   Must be called within <function><link linkend="API-console-lock">console_lock</link></function>;.
</para>
</refsect1>
</refentry>

<refentry id="API-printk-timed-ratelimit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>printk_timed_ratelimit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>printk_timed_ratelimit</refname>
 <refpurpose>
     caller-controlled printk ratelimiting
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>printk_timed_ratelimit </function></funcdef>
   <paramdef>unsigned long * <parameter>caller_jiffies</parameter></paramdef>
   <paramdef>unsigned int <parameter>interval_msecs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>caller_jiffies</parameter></term>
   <listitem>
    <para>
     pointer to caller's state
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>interval_msecs</parameter></term>
   <listitem>
    <para>
     minimum interval between prints
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function><link linkend="API-printk-timed-ratelimit">printk_timed_ratelimit</link></function> returns true if more than <parameter>interval_msecs</parameter>
   milliseconds have elapsed since the last time <function><link linkend="API-printk-timed-ratelimit">printk_timed_ratelimit</link></function>
   returned true.
</para>
</refsect1>
</refentry>

<refentry id="API-kmsg-dump-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmsg_dump_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmsg_dump_register</refname>
 <refpurpose>
     register a kernel log dumper.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kmsg_dump_register </function></funcdef>
   <paramdef>struct kmsg_dumper * <parameter>dumper</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dumper</parameter></term>
   <listitem>
    <para>
     pointer to the kmsg_dumper structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds a kernel log dumper to the system. The dump callback in the
   structure will be called when the kernel oopses or panics and must be
   set. Returns zero on success and <constant>-EINVAL</constant> or <constant>-EBUSY</constant> otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-kmsg-dump-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmsg_dump_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmsg_dump_unregister</refname>
 <refpurpose>
     unregister a kmsg dumper.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kmsg_dump_unregister </function></funcdef>
   <paramdef>struct kmsg_dumper * <parameter>dumper</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dumper</parameter></term>
   <listitem>
    <para>
     pointer to the kmsg_dumper structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes a dump device from the system. Returns zero on success and
   <constant>-EINVAL</constant> otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-kmsg-dump-get-line">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmsg_dump_get_line</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmsg_dump_get_line</refname>
 <refpurpose>
     retrieve one kmsg log line
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>kmsg_dump_get_line </function></funcdef>
   <paramdef>struct kmsg_dumper * <parameter>dumper</parameter></paramdef>
   <paramdef>bool <parameter>syslog</parameter></paramdef>
   <paramdef>char * <parameter>line</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>size_t * <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dumper</parameter></term>
   <listitem>
    <para>
     registered kmsg dumper
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>syslog</parameter></term>
   <listitem>
    <para>
     include the <quote>&lt;4&gt;</quote> prefixes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>line</parameter></term>
   <listitem>
    <para>
     buffer to copy the line to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     maximum size of the buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of line placed into buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Start at the beginning of the kmsg buffer, with the oldest kmsg
   record, and copy one record into the provided buffer.
   </para><para>

   Consecutive calls will return the next available record moving
   towards the end of the buffer with the youngest messages.
   </para><para>

   A return value of FALSE indicates that there are no more records to
   read.
</para>
</refsect1>
</refentry>

<refentry id="API-kmsg-dump-get-buffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmsg_dump_get_buffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmsg_dump_get_buffer</refname>
 <refpurpose>
     copy kmsg log lines
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>kmsg_dump_get_buffer </function></funcdef>
   <paramdef>struct kmsg_dumper * <parameter>dumper</parameter></paramdef>
   <paramdef>bool <parameter>syslog</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>size_t * <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dumper</parameter></term>
   <listitem>
    <para>
     registered kmsg dumper
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>syslog</parameter></term>
   <listitem>
    <para>
     include the <quote>&lt;4&gt;</quote> prefixes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     buffer to copy the line to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     maximum size of the buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of line placed into buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Start at the end of the kmsg buffer and fill the provided buffer
   with as many of the the *youngest* kmsg records that fit into it.
   If the buffer is large enough, all available kmsg records will be
   copied with a single call.
   </para><para>

   Consecutive calls will fill the buffer with the next block of
   available older records, not including the earlier retrieved ones.
   </para><para>

   A return value of FALSE indicates that there are no more records to
   read.
</para>
</refsect1>
</refentry>

<refentry id="API-kmsg-dump-rewind">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmsg_dump_rewind</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmsg_dump_rewind</refname>
 <refpurpose>
     reset the interator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kmsg_dump_rewind </function></funcdef>
   <paramdef>struct kmsg_dumper * <parameter>dumper</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dumper</parameter></term>
   <listitem>
    <para>
     registered kmsg dumper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reset the dumper's iterator so that <function><link linkend="API-kmsg-dump-get-line">kmsg_dump_get_line</link></function> and
   <function><link linkend="API-kmsg-dump-get-buffer">kmsg_dump_get_buffer</link></function> can be called again and used multiple
   times within the same dumper.<function>dump</function> callback.
</para>
</refsect1>
</refentry>

<!-- kernel/panic.c -->
<refentry id="API-panic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>panic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>panic</refname>
 <refpurpose>
  halt the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>panic </function></funcdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The text string to print
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Display a message, then perform cleanups.
   </para><para>

   This function never returns.
</para>
</refsect1>
</refentry>

<refentry id="API-add-taint">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>add_taint</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>add_taint</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>add_taint </function></funcdef>
   <paramdef>unsigned <parameter>flag</parameter></paramdef>
   <paramdef>enum lockdep_ok <parameter>lockdep_ok</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>flag</parameter></term>
   <listitem>
    <para>
     one of the TAINT_* constants.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lockdep_ok</parameter></term>
   <listitem>
    <para>
     whether lock debugging is still OK.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If something bad has gone wrong, you'll want <parameter>lockdebug_ok</parameter> = false, but for
   some notewortht-but-not-corrupting cases, it can be set to true.
</para>
</refsect1>
</refentry>

<!-- kernel/sys.c -->
<refentry>
 <refnamediv>
  <refname>
   kernel/sys.c
  </refname>
  <refpurpose>
   Document generation inconsistency
  </refpurpose>
 </refnamediv>
 <refsect1>
  <title>
   Oops
  </title>
  <warning>
   <para>
    The template for this document tried to insert
    the structured comment from the file
    <filename>kernel/sys.c</filename> at this point,
    but none was found.
    This dummy section is inserted to allow
    generation to continue.
   </para>
  </warning>
 </refsect1>
</refentry>
<!-- kernel/rcu/srcu.c -->
<refentry id="API-init-srcu-struct">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>init_srcu_struct</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>init_srcu_struct</refname>
 <refpurpose>
  initialize a sleep-RCU structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>init_srcu_struct </function></funcdef>
   <paramdef>struct srcu_struct * <parameter>sp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sp</parameter></term>
   <listitem>
    <para>
     structure to initialize.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Must invoke this on a given srcu_struct before passing that srcu_struct
   to any other function.  Each srcu_struct represents a separate domain
   of SRCU protection.
</para>
</refsect1>
</refentry>

<refentry id="API-cleanup-srcu-struct">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cleanup_srcu_struct</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cleanup_srcu_struct</refname>
 <refpurpose>
     deconstruct a sleep-RCU structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>cleanup_srcu_struct </function></funcdef>
   <paramdef>struct srcu_struct * <parameter>sp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sp</parameter></term>
   <listitem>
    <para>
     structure to clean up.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Must invoke this after you are finished using a given srcu_struct that
   was initialized via <function><link linkend="API-init-srcu-struct">init_srcu_struct</link></function>, else you leak memory.
</para>
</refsect1>
</refentry>

<refentry id="API-synchronize-srcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>synchronize_srcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>synchronize_srcu</refname>
 <refpurpose>
     wait for prior SRCU read-side critical-section completion
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>synchronize_srcu </function></funcdef>
   <paramdef>struct srcu_struct * <parameter>sp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sp</parameter></term>
   <listitem>
    <para>
     srcu_struct with which to synchronize.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Wait for the count to drain to zero of both indexes. To avoid the
   possible starvation of <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function>, it waits for the count of
   the index=((-&gt;completed &amp; 1) ^ 1) to drain to zero at first,
   and then flip the completed and wait for the count of the other index.
   </para><para>

   Can block; must be called from process context.
   </para><para>

   Note that it is illegal to call <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function> from the corresponding
   SRCU read-side critical section; doing so will result in deadlock.
   However, it is perfectly legal to call <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function> on one
   srcu_struct from some other srcu_struct's read-side critical section,
   as long as the resulting graph of srcu_structs is acyclic.
   </para><para>

   There are memory-ordering constraints implied by <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function>.
   On systems with more than one CPU, when <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function> returns,
   each CPU is guaranteed to have executed a full memory barrier since
   the end of its last corresponding SRCU-sched read-side critical section
   whose beginning preceded the call to <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function>.  In addition,
   each CPU having an SRCU read-side critical section that extends beyond
   the return from <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function> is guaranteed to have executed a
   full memory barrier after the beginning of <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function> and before
   the beginning of that SRCU read-side critical section.  Note that these
   guarantees include CPUs that are offline, idle, or executing in user mode,
   as well as CPUs that are executing in the kernel.
   </para><para>

   Furthermore, if CPU A invoked <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function>, which returned
   to its caller on CPU B, then both CPU A and CPU B are guaranteed
   to have executed a full memory barrier during the execution of
   <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function>.  This guarantee applies even if CPU A and CPU B
   are the same CPU, but again only if the system has more than one CPU.
   </para><para>

   Of course, these memory-ordering guarantees apply only when
   <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function>, <function>srcu_read_lock</function>, and <function>srcu_read_unlock</function> are
   passed the same srcu_struct structure.
</para>
</refsect1>
</refentry>

<refentry id="API-synchronize-srcu-expedited">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>synchronize_srcu_expedited</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>synchronize_srcu_expedited</refname>
 <refpurpose>
     Brute-force SRCU grace period
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>synchronize_srcu_expedited </function></funcdef>
   <paramdef>struct srcu_struct * <parameter>sp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sp</parameter></term>
   <listitem>
    <para>
     srcu_struct with which to synchronize.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Wait for an SRCU grace period to elapse, but be more aggressive about
   spinning rather than blocking when waiting.
   </para><para>

   Note that <function><link linkend="API-synchronize-srcu-expedited">synchronize_srcu_expedited</link></function> has the same deadlock and
   memory-ordering properties as does <function><link linkend="API-synchronize-srcu">synchronize_srcu</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-srcu-barrier">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>srcu_barrier</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>srcu_barrier</refname>
 <refpurpose>
     Wait until all in-flight <function>call_srcu</function> callbacks complete.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>srcu_barrier </function></funcdef>
   <paramdef>struct srcu_struct * <parameter>sp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sp</parameter></term>
   <listitem>
    <para>
     srcu_struct on which to wait for in-flight callbacks.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-srcu-batches-completed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>srcu_batches_completed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>srcu_batches_completed</refname>
 <refpurpose>
     return batches completed.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>srcu_batches_completed </function></funcdef>
   <paramdef>struct srcu_struct * <parameter>sp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sp</parameter></term>
   <listitem>
    <para>
     srcu_struct on which to report batch completion.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Report the number of batches, correlated with, but not necessarily
   precisely the same as, the number of grace periods that have elapsed.
</para>
</refsect1>
</refentry>

<!-- kernel/rcu/tree.c -->
<refentry id="API-rcu-idle-enter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_idle_enter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_idle_enter</refname>
 <refpurpose>
  inform RCU that current CPU is entering idle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>rcu_idle_enter </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Enter idle mode, in other words, -leave- the mode in which RCU
   read-side critical sections can occur.  (Though RCU read-side
   critical sections can occur in irq handlers in idle, a possibility
   handled by <function>irq_enter</function> and <function>irq_exit</function>.)
   </para><para>

   We crowbar the -&gt;dynticks_nesting field to zero to allow for
   the possibility of usermode upcalls having messed up our count
   of interrupt nesting level during the prior busy period.
</para>
</refsect1>
</refentry>

<refentry id="API-rcu-idle-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_idle_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_idle_exit</refname>
 <refpurpose>
     inform RCU that current CPU is leaving idle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>rcu_idle_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Exit idle mode, in other words, -enter- the mode in which RCU
   read-side critical sections can occur.
   </para><para>

   We crowbar the -&gt;dynticks_nesting field to DYNTICK_TASK_NEST to
   allow for the possibility of usermode upcalls messing up our count
   of interrupt nesting level during the busy period that is just
   now starting.
</para>
</refsect1>
</refentry>

<refentry id="API-rcu-is-watching">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_is_watching</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_is_watching</refname>
 <refpurpose>
     see if RCU thinks that the current CPU is idle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool notrace <function>rcu_is_watching </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   If the current CPU is in its idle loop and is neither in an interrupt
   or NMI handler, return true.
</para>
</refsect1>
</refentry>

<refentry id="API-synchronize-sched">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>synchronize_sched</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>synchronize_sched</refname>
 <refpurpose>
     wait until an rcu-sched grace period has elapsed.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>synchronize_sched </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Control will return to the caller some time after a full rcu-sched
   grace period has elapsed, in other words after all currently executing
   rcu-sched read-side critical sections have completed.   These read-side
   critical sections are delimited by <function>rcu_read_lock_sched</function> and
   <function>rcu_read_unlock_sched</function>, and may be nested.  Note that <function>preempt_disable</function>,
   <function>local_irq_disable</function>, and so on may be used in place of
   <function>rcu_read_lock_sched</function>.
   </para><para>

   This means that all preempt_disable code sequences, including NMI and
   non-threaded hardware-interrupt handlers, in progress on entry will
   have completed before this primitive returns.  However, this does not
   guarantee that softirq handlers will have completed, since in some
   kernels, these handlers can run in process context, and can block.
   </para><para>

   Note that this guarantee implies further memory-ordering guarantees.
   On systems with more than one CPU, when <function><link linkend="API-synchronize-sched">synchronize_sched</link></function> returns,
   each CPU is guaranteed to have executed a full memory barrier since the
   end of its last RCU-sched read-side critical section whose beginning
   preceded the call to <function><link linkend="API-synchronize-sched">synchronize_sched</link></function>.  In addition, each CPU having
   an RCU read-side critical section that extends beyond the return from
   <function><link linkend="API-synchronize-sched">synchronize_sched</link></function> is guaranteed to have executed a full memory barrier
   after the beginning of <function><link linkend="API-synchronize-sched">synchronize_sched</link></function> and before the beginning of
   that RCU read-side critical section.  Note that these guarantees include
   CPUs that are offline, idle, or executing in user mode, as well as CPUs
   that are executing in the kernel.
   </para><para>

   Furthermore, if CPU A invoked <function><link linkend="API-synchronize-sched">synchronize_sched</link></function>, which returned
   to its caller on CPU B, then both CPU A and CPU B are guaranteed
   to have executed a full memory barrier during the execution of
   <function><link linkend="API-synchronize-sched">synchronize_sched</link></function> -- even if CPU A and CPU B are the same CPU (but
   again only if the system has more than one CPU).
   </para><para>

   This primitive provides the guarantees made by the (now removed)
   <function>synchronize_kernel</function> API.  In contrast, <function><link linkend="API-synchronize-rcu">synchronize_rcu</link></function> only
   guarantees that <function>rcu_read_lock</function> sections will have completed.
   In <quote>classic RCU</quote>, these two guarantees happen to be one and
   the same, but can differ in realtime RCU implementations.
</para>
</refsect1>
</refentry>

<refentry id="API-synchronize-rcu-bh">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>synchronize_rcu_bh</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>synchronize_rcu_bh</refname>
 <refpurpose>
     wait until an rcu_bh grace period has elapsed.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>synchronize_rcu_bh </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Control will return to the caller some time after a full rcu_bh grace
   period has elapsed, in other words after all currently executing rcu_bh
   read-side critical sections have completed.  RCU read-side critical
   sections are delimited by <function>rcu_read_lock_bh</function> and <function>rcu_read_unlock_bh</function>,
   and may be nested.
   </para><para>

   See the description of <function><link linkend="API-synchronize-sched">synchronize_sched</link></function> for more detailed information
   on memory ordering guarantees.
</para>
</refsect1>
</refentry>

<refentry id="API-get-state-synchronize-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_state_synchronize_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_state_synchronize_rcu</refname>
 <refpurpose>
     Snapshot current RCU state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>get_state_synchronize_rcu </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns a cookie that is used by a later call to <function><link linkend="API-cond-synchronize-rcu">cond_synchronize_rcu</link></function>
   to determine whether or not a full grace period has elapsed in the
   meantime.
</para>
</refsect1>
</refentry>

<refentry id="API-cond-synchronize-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cond_synchronize_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cond_synchronize_rcu</refname>
 <refpurpose>
     Conditionally wait for an RCU grace period
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>cond_synchronize_rcu </function></funcdef>
   <paramdef>unsigned long <parameter>oldstate</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>oldstate</parameter></term>
   <listitem>
    <para>
     return value from earlier call to <function><link linkend="API-get-state-synchronize-rcu">get_state_synchronize_rcu</link></function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a full RCU grace period has elapsed since the earlier call to
   <function><link linkend="API-get-state-synchronize-rcu">get_state_synchronize_rcu</link></function>, just return.  Otherwise, invoke
   <function><link linkend="API-synchronize-rcu">synchronize_rcu</link></function> to wait for a full grace period.
   </para><para>

   Yes, this function does not take counter wrap into account.  But
   counter wrap is harmless.  If the counter wraps, we have waited for
   more than 2 billion grace periods (and way more on a 64-bit system!),
   so waiting for one additional grace period should be just fine.
</para>
</refsect1>
</refentry>

<refentry id="API-get-state-synchronize-sched">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_state_synchronize_sched</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_state_synchronize_sched</refname>
 <refpurpose>
     Snapshot current RCU-sched state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>get_state_synchronize_sched </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns a cookie that is used by a later call to <function><link linkend="API-cond-synchronize-sched">cond_synchronize_sched</link></function>
   to determine whether or not a full grace period has elapsed in the
   meantime.
</para>
</refsect1>
</refentry>

<refentry id="API-cond-synchronize-sched">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cond_synchronize_sched</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cond_synchronize_sched</refname>
 <refpurpose>
     Conditionally wait for an RCU-sched grace period
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>cond_synchronize_sched </function></funcdef>
   <paramdef>unsigned long <parameter>oldstate</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>oldstate</parameter></term>
   <listitem>
    <para>
     return value from earlier call to <function><link linkend="API-get-state-synchronize-sched">get_state_synchronize_sched</link></function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a full RCU-sched grace period has elapsed since the earlier call to
   <function><link linkend="API-get-state-synchronize-sched">get_state_synchronize_sched</link></function>, just return.  Otherwise, invoke
   <function><link linkend="API-synchronize-sched">synchronize_sched</link></function> to wait for a full grace period.
   </para><para>

   Yes, this function does not take counter wrap into account.  But
   counter wrap is harmless.  If the counter wraps, we have waited for
   more than 2 billion grace periods (and way more on a 64-bit system!),
   so waiting for one additional grace period should be just fine.
</para>
</refsect1>
</refentry>

<refentry id="API-synchronize-sched-expedited">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>synchronize_sched_expedited</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>synchronize_sched_expedited</refname>
 <refpurpose>
     Brute-force RCU-sched grace period
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>synchronize_sched_expedited </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Wait for an RCU-sched grace period to elapse, but use a <quote>big hammer</quote>
   approach to force the grace period to end quickly.  This consumes
   significant time on all CPUs and is unfriendly to real-time workloads,
   so is thus not recommended for any sort of common-case code.  In fact,
   if you are using <function><link linkend="API-synchronize-sched-expedited">synchronize_sched_expedited</link></function> in a loop, please
   restructure your code to batch your updates, and then use a single
   <function><link linkend="API-synchronize-sched">synchronize_sched</link></function> instead.
   </para><para>

   This implementation can be thought of as an application of sequence
   locking to expedited grace periods, but using the sequence counter to
   determine when someone else has already done the work instead of for
   retrying readers.
</para>
</refsect1>
</refentry>

<refentry id="API-rcu-barrier-bh">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_barrier_bh</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_barrier_bh</refname>
 <refpurpose>
     Wait until all in-flight <function>call_rcu_bh</function> callbacks complete.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>rcu_barrier_bh </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-rcu-barrier-sched">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_barrier_sched</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_barrier_sched</refname>
 <refpurpose>
     Wait for in-flight <function>call_rcu_sched</function> callbacks.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>rcu_barrier_sched </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- kernel/rcu/tree_plugin.h -->
<refentry id="API-synchronize-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>synchronize_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>synchronize_rcu</refname>
 <refpurpose>
  wait until a grace period has elapsed.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>synchronize_rcu </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Control will return to the caller some time after a full grace
   period has elapsed, in other words after all currently executing RCU
   read-side critical sections have completed.  Note, however, that
   upon return from <function><link linkend="API-synchronize-rcu">synchronize_rcu</link></function>, the caller might well be executing
   concurrently with new RCU read-side critical sections that began while
   <function><link linkend="API-synchronize-rcu">synchronize_rcu</link></function> was waiting.  RCU read-side critical sections are
   delimited by <function>rcu_read_lock</function> and <function>rcu_read_unlock</function>, and may be nested.
   </para><para>

   See the description of <function><link linkend="API-synchronize-sched">synchronize_sched</link></function> for more detailed information
   on memory ordering guarantees.
</para>
</refsect1>
</refentry>

<refentry id="API-synchronize-rcu-expedited">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>synchronize_rcu_expedited</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>synchronize_rcu_expedited</refname>
 <refpurpose>
     Brute-force RCU grace period
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>synchronize_rcu_expedited </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Wait for an RCU-preempt grace period, but expedite it.  The basic
   idea is to invoke <function><link linkend="API-synchronize-sched-expedited">synchronize_sched_expedited</link></function> to push all the tasks to
   the -&gt;blkd_tasks lists and wait for this list to drain.  This consumes
   significant time on all CPUs and is unfriendly to real-time workloads,
   so is thus not recommended for any sort of common-case code.
   In fact, if you are using <function><link linkend="API-synchronize-rcu-expedited">synchronize_rcu_expedited</link></function> in a loop,
   please restructure your code to batch your updates, and then Use a
   single <function><link linkend="API-synchronize-rcu">synchronize_rcu</link></function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-rcu-barrier">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_barrier</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_barrier</refname>
 <refpurpose>
     Wait until all in-flight <function>call_rcu</function> callbacks complete.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>rcu_barrier </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Note that this primitive does not necessarily wait for an RCU grace period
   to complete.  For example, if there are no RCU callbacks queued anywhere
   in the system, then <function><link linkend="API-rcu-barrier">rcu_barrier</link></function> is within its rights to return
   immediately, without waiting for anything, much less an RCU grace period.
</para>
</refsect1>
</refentry>

<!-- kernel/rcu/update.c -->
<refentry id="API-rcu-read-lock-sched-held">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_read_lock_sched_held</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_read_lock_sched_held</refname>
 <refpurpose>
  might we be in RCU-sched read-side critical section?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>rcu_read_lock_sched_held </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   If CONFIG_DEBUG_LOCK_ALLOC is selected, returns nonzero iff in an
   RCU-sched read-side critical section.  In absence of
   CONFIG_DEBUG_LOCK_ALLOC, this assumes we are in an RCU-sched read-side
   critical section unless it can prove otherwise.  Note that disabling
   of preemption (including disabling irqs) counts as an RCU-sched
   read-side critical section.  This is useful for debug checks in functions
   that required that they be called within an RCU-sched read-side
   critical section.
   </para><para>

   Check <function>debug_lockdep_rcu_enabled</function> to prevent false positives during boot
   and while lockdep is disabled.
   </para><para>

   Note that if the CPU is in the idle loop from an RCU point of
   view (ie: that we are in the section between <function><link linkend="API-rcu-idle-enter">rcu_idle_enter</link></function> and
   <function><link linkend="API-rcu-idle-exit">rcu_idle_exit</link></function>) then <function><link linkend="API-rcu-read-lock-held">rcu_read_lock_held</link></function> returns false even if the CPU
   did an <function>rcu_read_lock</function>.  The reason for this is that RCU ignores CPUs
   that are in such a section, considering these as in extended quiescent
   state, so such a CPU is effectively never in an RCU read-side critical
   section regardless of what RCU primitives it invokes.  This state of
   affairs is required --- we need to keep an RCU-free window in idle
   where the CPU may possibly enter into low power mode. This way we can
   notice an extended quiescent state to other CPUs that started a grace
   period. Otherwise we would delay any grace period as long as we run in
   the idle task.
   </para><para>

   Similarly, we avoid claiming an SRCU read lock held if the current
   CPU is offline.
</para>
</refsect1>
</refentry>

<refentry id="API-rcu-expedite-gp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_expedite_gp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_expedite_gp</refname>
 <refpurpose>
     Expedite future RCU grace periods
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>rcu_expedite_gp </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   After a call to this function, future calls to <function><link linkend="API-synchronize-rcu">synchronize_rcu</link></function> and
   friends act as the corresponding <function><link linkend="API-synchronize-rcu-expedited">synchronize_rcu_expedited</link></function> function
   had instead been called.
</para>
</refsect1>
</refentry>

<refentry id="API-rcu-unexpedite-gp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_unexpedite_gp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_unexpedite_gp</refname>
 <refpurpose>
     Cancel prior <function><link linkend="API-rcu-expedite-gp">rcu_expedite_gp</link></function> invocation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>rcu_unexpedite_gp </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Undo a prior call to <function><link linkend="API-rcu-expedite-gp">rcu_expedite_gp</link></function>.  If all prior calls to
   <function><link linkend="API-rcu-expedite-gp">rcu_expedite_gp</link></function> are undone by a subsequent call to <function><link linkend="API-rcu-unexpedite-gp">rcu_unexpedite_gp</link></function>,
   and if the rcu_expedited sysfs/boot parameter is not set, then all
   subsequent calls to <function><link linkend="API-synchronize-rcu">synchronize_rcu</link></function> and friends will return to
   their normal non-expedited behavior.
</para>
</refsect1>
</refentry>

<refentry id="API-rcu-read-lock-held">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_read_lock_held</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_read_lock_held</refname>
 <refpurpose>
     might we be in RCU read-side critical section?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>rcu_read_lock_held </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   If CONFIG_DEBUG_LOCK_ALLOC is selected, returns nonzero iff in an RCU
   read-side critical section.  In absence of CONFIG_DEBUG_LOCK_ALLOC,
   this assumes we are in an RCU read-side critical section unless it can
   prove otherwise.  This is useful for debug checks in functions that
   require that they be called within an RCU read-side critical section.
   </para><para>

   Checks <function>debug_lockdep_rcu_enabled</function> to prevent false positives during boot
   and while lockdep is disabled.
   </para><para>

   Note that <function>rcu_read_lock</function> and the matching <function>rcu_read_unlock</function> must
   occur in the same context, for example, it is illegal to invoke
   <function>rcu_read_unlock</function> in process context if the matching <function>rcu_read_lock</function>
   was invoked from within an irq handler.
   </para><para>

   Note that <function>rcu_read_lock</function> is disallowed if the CPU is either idle or
   offline from an RCU perspective, so check for those as well.
</para>
</refsect1>
</refentry>

<refentry id="API-rcu-read-lock-bh-held">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_read_lock_bh_held</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_read_lock_bh_held</refname>
 <refpurpose>
     might we be in RCU-bh read-side critical section?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>rcu_read_lock_bh_held </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Check for bottom half being disabled, which covers both the
   CONFIG_PROVE_RCU and not cases.  Note that if someone uses
   <function>rcu_read_lock_bh</function>, but then later enables BH, lockdep (if enabled)
   will show the situation.  This is useful for debug checks in functions
   that require that they be called within an RCU read-side critical
   section.
   </para><para>

   Check <function>debug_lockdep_rcu_enabled</function> to prevent false positives during boot.
   </para><para>

   Note that <function>rcu_read_lock</function> is disallowed if the CPU is either idle or
   offline from an RCU perspective, so check for those as well.
</para>
</refsect1>
</refentry>

<refentry id="API-wakeme-after-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wakeme_after_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wakeme_after_rcu</refname>
 <refpurpose>
     Callback function to awaken a task after grace period
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>wakeme_after_rcu </function></funcdef>
   <paramdef>struct rcu_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     Pointer to rcu_head member within rcu_synchronize structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Awaken the corresponding task now that a grace period has elapsed.
</para>
</refsect1>
</refentry>

<refentry id="API-init-rcu-head-on-stack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>init_rcu_head_on_stack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>init_rcu_head_on_stack</refname>
 <refpurpose>
     initialize on-stack rcu_head for debugobjects
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>init_rcu_head_on_stack </function></funcdef>
   <paramdef>struct rcu_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     pointer to rcu_head structure to be initialized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function informs debugobjects of a new rcu_head structure that
   has been allocated as an auto variable on the stack.  This function
   is not required for rcu_head structures that are statically defined or
   that are dynamically allocated on the heap.  This function has no
   effect for !CONFIG_DEBUG_OBJECTS_RCU_HEAD kernel builds.
</para>
</refsect1>
</refentry>

<refentry id="API-destroy-rcu-head-on-stack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>destroy_rcu_head_on_stack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>destroy_rcu_head_on_stack</refname>
 <refpurpose>
     destroy on-stack rcu_head for debugobjects
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>destroy_rcu_head_on_stack </function></funcdef>
   <paramdef>struct rcu_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     pointer to rcu_head structure to be initialized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function informs debugobjects that an on-stack rcu_head structure
   is about to go out of scope.  As with <function><link linkend="API-init-rcu-head-on-stack">init_rcu_head_on_stack</link></function>, this
   function is not required for rcu_head structures that are statically
   defined or that are dynamically allocated on the heap.  Also as with
   <function><link linkend="API-init-rcu-head-on-stack">init_rcu_head_on_stack</link></function>, this function has no effect for
   !CONFIG_DEBUG_OBJECTS_RCU_HEAD kernel builds.
</para>
</refsect1>
</refentry>

<refentry id="API-synchronize-rcu-tasks">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>synchronize_rcu_tasks</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>synchronize_rcu_tasks</refname>
 <refpurpose>
     wait until an rcu-tasks grace period has elapsed.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>synchronize_rcu_tasks </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Control will return to the caller some time after a full rcu-tasks
   grace period has elapsed, in other words after all currently
   executing rcu-tasks read-side critical sections have elapsed.  These
   read-side critical sections are delimited by calls to <function>schedule</function>,
   <function>cond_resched_rcu_qs</function>, idle execution, userspace execution, calls
   to <function><link linkend="API-synchronize-rcu-tasks">synchronize_rcu_tasks</link></function>, and (in theory, anyway) <function>cond_resched</function>.
   </para><para>

   This is a very specialized primitive, intended only for a few uses in
   tracing and other situations requiring manipulation of function
   preambles and profiling hooks.  The <function><link linkend="API-synchronize-rcu-tasks">synchronize_rcu_tasks</link></function> function
   is not (yet) intended for heavy use from multiple CPUs.
   </para><para>

   Note that this guarantee implies further memory-ordering guarantees.
   On systems with more than one CPU, when <function><link linkend="API-synchronize-rcu-tasks">synchronize_rcu_tasks</link></function> returns,
   each CPU is guaranteed to have executed a full memory barrier since the
   end of its last RCU-tasks read-side critical section whose beginning
   preceded the call to <function><link linkend="API-synchronize-rcu-tasks">synchronize_rcu_tasks</link></function>.  In addition, each CPU
   having an RCU-tasks read-side critical section that extends beyond
   the return from <function><link linkend="API-synchronize-rcu-tasks">synchronize_rcu_tasks</link></function> is guaranteed to have executed
   a full memory barrier after the beginning of <function><link linkend="API-synchronize-rcu-tasks">synchronize_rcu_tasks</link></function>
   and before the beginning of that RCU-tasks read-side critical section.
   Note that these guarantees include CPUs that are offline, idle, or
   executing in user mode, as well as CPUs that are executing in the kernel.
   </para><para>

   Furthermore, if CPU A invoked <function><link linkend="API-synchronize-rcu-tasks">synchronize_rcu_tasks</link></function>, which returned
   to its caller on CPU B, then both CPU A and CPU B are guaranteed
   to have executed a full memory barrier during the execution of
   <function><link linkend="API-synchronize-rcu-tasks">synchronize_rcu_tasks</link></function> -- even if CPU A and CPU B are the same CPU
   (but again only if the system has more than one CPU).
</para>
</refsect1>
</refentry>

<refentry id="API-rcu-barrier-tasks">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rcu_barrier_tasks</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_barrier_tasks</refname>
 <refpurpose>
     Wait for in-flight <function>call_rcu_tasks</function> callbacks.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>rcu_barrier_tasks </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Although the current implementation is guaranteed to wait, it is not
   obligated to, for example, if there are no pending callbacks.
</para>
</refsect1>
</refentry>

     </sect1>

     <sect1><title>Device Resource Management</title>
<!-- drivers/base/devres.c -->
<refentry id="API-devres-alloc-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_alloc_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_alloc_node</refname>
 <refpurpose>
  Allocate device resource data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>devres_alloc_node </function></funcdef>
   <paramdef>dr_release_t <parameter>release</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
   <paramdef>int <parameter>nid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>release</parameter></term>
   <listitem>
    <para>
     Release function devres will be associated with
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Allocation size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     Allocation flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nid</parameter></term>
   <listitem>
    <para>
     NUMA node
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate devres of <parameter>size</parameter> bytes.  The allocated area is zeroed, then
   associated with <parameter>release</parameter>.  The returned pointer can be passed to
   other devres_*() functions.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to allocated devres on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-devres-for-each-res">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_for_each_res</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_for_each_res</refname>
 <refpurpose>
     Resource iterator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>devres_for_each_res </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>dr_release_t <parameter>release</parameter></paramdef>
   <paramdef>dr_match_t <parameter>match</parameter></paramdef>
   <paramdef>void * <parameter>match_data</parameter></paramdef>
   <paramdef>void (*<parameter>fn</parameter>)
     <funcparams>struct device *, void *, void *</funcparams></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to iterate resource from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>release</parameter></term>
   <listitem>
    <para>
     Look for resources associated with this release function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match</parameter></term>
   <listitem>
    <para>
     Match function (optional)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match_data</parameter></term>
   <listitem>
    <para>
     Data for the match function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     Function to be called for each matched resource.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     Data for <parameter>fn</parameter>, the 3rd parameter of <parameter>fn</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Call <parameter>fn</parameter> for each devres of <parameter>dev</parameter> which is associated with <parameter>release</parameter>
   and for which <parameter>match</parameter> returns 1.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   void
</para>
</refsect1>
</refentry>

<refentry id="API-devres-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_free</refname>
 <refpurpose>
     Free device resource data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>devres_free </function></funcdef>
   <paramdef>void * <parameter>res</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     Pointer to devres data to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free devres created with <function>devres_alloc</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-devres-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_add</refname>
 <refpurpose>
     Register device resource
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>devres_add </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>res</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to add resource to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     Resource to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register devres <parameter>res</parameter> to <parameter>dev</parameter>.  <parameter>res</parameter> should have been allocated
   using <function>devres_alloc</function>.  On driver detach, the associated release
   function will be invoked and devres will be freed automatically.
</para>
</refsect1>
</refentry>

<refentry id="API-devres-find">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_find</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_find</refname>
 <refpurpose>
     Find device resource
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>devres_find </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>dr_release_t <parameter>release</parameter></paramdef>
   <paramdef>dr_match_t <parameter>match</parameter></paramdef>
   <paramdef>void * <parameter>match_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to lookup resource from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>release</parameter></term>
   <listitem>
    <para>
     Look for resources associated with this release function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match</parameter></term>
   <listitem>
    <para>
     Match function (optional)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match_data</parameter></term>
   <listitem>
    <para>
     Data for the match function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Find the latest devres of <parameter>dev</parameter> which is associated with <parameter>release</parameter>
   and for which <parameter>match</parameter> returns 1.  If <parameter>match</parameter> is NULL, it's considered
   to match all.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to found devres, NULL if not found.
</para>
</refsect1>
</refentry>

<refentry id="API-devres-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_get</refname>
 <refpurpose>
     Find devres, if non-existent, add one atomically
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>devres_get </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>new_res</parameter></paramdef>
   <paramdef>dr_match_t <parameter>match</parameter></paramdef>
   <paramdef>void * <parameter>match_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to lookup or add devres for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_res</parameter></term>
   <listitem>
    <para>
     Pointer to new initialized devres to add if not found
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match</parameter></term>
   <listitem>
    <para>
     Match function (optional)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match_data</parameter></term>
   <listitem>
    <para>
     Data for the match function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Find the latest devres of <parameter>dev</parameter> which has the same release function
   as <parameter>new_res</parameter> and for which <parameter>match</parameter> return 1.  If found, <parameter>new_res</parameter> is
   freed; otherwise, <parameter>new_res</parameter> is added atomically.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to found or added devres.
</para>
</refsect1>
</refentry>

<refentry id="API-devres-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_remove</refname>
 <refpurpose>
     Find a device resource and remove it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>devres_remove </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>dr_release_t <parameter>release</parameter></paramdef>
   <paramdef>dr_match_t <parameter>match</parameter></paramdef>
   <paramdef>void * <parameter>match_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to find resource from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>release</parameter></term>
   <listitem>
    <para>
     Look for resources associated with this release function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match</parameter></term>
   <listitem>
    <para>
     Match function (optional)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match_data</parameter></term>
   <listitem>
    <para>
     Data for the match function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Find the latest devres of <parameter>dev</parameter> associated with <parameter>release</parameter> and for
   which <parameter>match</parameter> returns 1.  If <parameter>match</parameter> is NULL, it's considered to
   match all.  If found, the resource is removed atomically and
   returned.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to removed devres on success, NULL if not found.
</para>
</refsect1>
</refentry>

<refentry id="API-devres-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_destroy</refname>
 <refpurpose>
     Find a device resource and destroy it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>devres_destroy </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>dr_release_t <parameter>release</parameter></paramdef>
   <paramdef>dr_match_t <parameter>match</parameter></paramdef>
   <paramdef>void * <parameter>match_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to find resource from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>release</parameter></term>
   <listitem>
    <para>
     Look for resources associated with this release function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match</parameter></term>
   <listitem>
    <para>
     Match function (optional)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match_data</parameter></term>
   <listitem>
    <para>
     Data for the match function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Find the latest devres of <parameter>dev</parameter> associated with <parameter>release</parameter> and for
   which <parameter>match</parameter> returns 1.  If <parameter>match</parameter> is NULL, it's considered to
   match all.  If found, the resource is removed atomically and freed.
   </para><para>

   Note that the release function for the resource will not be called,
   only the devres-allocated data will be freed.  The caller becomes
   responsible for freeing any other data.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 if devres is found and freed, -ENOENT if not found.
</para>
</refsect1>
</refentry>

<refentry id="API-devres-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_release</refname>
 <refpurpose>
     Find a device resource and destroy it, calling release
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>devres_release </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>dr_release_t <parameter>release</parameter></paramdef>
   <paramdef>dr_match_t <parameter>match</parameter></paramdef>
   <paramdef>void * <parameter>match_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to find resource from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>release</parameter></term>
   <listitem>
    <para>
     Look for resources associated with this release function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match</parameter></term>
   <listitem>
    <para>
     Match function (optional)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match_data</parameter></term>
   <listitem>
    <para>
     Data for the match function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Find the latest devres of <parameter>dev</parameter> associated with <parameter>release</parameter> and for
   which <parameter>match</parameter> returns 1.  If <parameter>match</parameter> is NULL, it's considered to
   match all.  If found, the resource is removed atomically, the
   release function called and the resource freed.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 if devres is found and freed, -ENOENT if not found.
</para>
</refsect1>
</refentry>

<refentry id="API-devres-open-group">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_open_group</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_open_group</refname>
 <refpurpose>
     Open a new devres group
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>devres_open_group </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>id</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to open devres group for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     Separator ID
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     Allocation flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Open a new devres group for <parameter>dev</parameter> with <parameter>id</parameter>.  For <parameter>id</parameter>, using a
   pointer to an object which won't be used for another group is
   recommended.  If <parameter>id</parameter> is NULL, address-wise unique ID is created.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   ID of the new group, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-devres-close-group">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_close_group</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_close_group</refname>
 <refpurpose>
     Close a devres group
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>devres_close_group </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to close devres group for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     ID of target group, can be NULL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Close the group identified by <parameter>id</parameter>.  If <parameter>id</parameter> is NULL, the latest open
   group is selected.
</para>
</refsect1>
</refentry>

<refentry id="API-devres-remove-group">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_remove_group</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_remove_group</refname>
 <refpurpose>
     Remove a devres group
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>devres_remove_group </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to remove group for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     ID of target group, can be NULL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove the group identified by <parameter>id</parameter>.  If <parameter>id</parameter> is NULL, the latest
   open group is selected.  Note that removing a group doesn't affect
   any other resources.
</para>
</refsect1>
</refentry>

<refentry id="API-devres-release-group">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_release_group</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_release_group</refname>
 <refpurpose>
     Release resources in a devres group
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>devres_release_group </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to release group for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     ID of target group, can be NULL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release all resources in the group identified by <parameter>id</parameter>.  If <parameter>id</parameter> is
   NULL, the latest open group is selected.  The selected group and
   groups properly nested inside the selected group are removed.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   The number of released non-group resources.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-add-action">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_add_action</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_add_action</refname>
 <refpurpose>
     add a custom action to list of managed resources
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>devm_add_action </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>void (*<parameter>action</parameter>)
     <funcparams>void *</funcparams></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device that owns the action
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>action</parameter></term>
   <listitem>
    <para>
     Function that should be called
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     Pointer to data passed to <parameter>action</parameter> implementation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This adds a custom action to the list of managed resources so that
   it gets executed as part of standard resource unwinding.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-remove-action">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_remove_action</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_remove_action</refname>
 <refpurpose>
     removes previously added custom action
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>devm_remove_action </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>void (*<parameter>action</parameter>)
     <funcparams>void *</funcparams></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device that owns the action
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>action</parameter></term>
   <listitem>
    <para>
     Function implementing the action
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     Pointer to data passed to <parameter>action</parameter> implementation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes instance of <parameter>action</parameter> previously added by <function><link linkend="API-devm-add-action">devm_add_action</link></function>.
   Both action and data should match one of the existing entries.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-kmalloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_kmalloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_kmalloc</refname>
 <refpurpose>
     Resource-managed kmalloc
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>devm_kmalloc </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to allocate memory for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Allocation size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     Allocation gfp flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Managed kmalloc.  Memory allocated with this function is
   automatically freed on driver detach.  Like all other devres
   resources, guaranteed alignment is unsigned long long.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to allocated memory on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-kstrdup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_kstrdup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_kstrdup</refname>
 <refpurpose>
     Allocate resource managed space and copy an existing string into that.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>devm_kstrdup </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to allocate memory for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     the string to duplicate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     the GFP mask used in the <function><link linkend="API-devm-kmalloc">devm_kmalloc</link></function> call when
     allocating memory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to allocated string on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-kvasprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_kvasprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_kvasprintf</refname>
 <refpurpose>
     Allocate resource managed space and format a string into that.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>devm_kvasprintf </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef>va_list <parameter>ap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to allocate memory for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     the GFP mask used in the <function><link linkend="API-devm-kmalloc">devm_kmalloc</link></function> call when
     allocating memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The <function>printf</function>-style format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ap</parameter></term>
   <listitem>
    <para>
     Arguments for the format string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to allocated string on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-kasprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_kasprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_kasprintf</refname>
 <refpurpose>
     Allocate resource managed space and format a string into that.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>devm_kasprintf </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to allocate memory for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     the GFP mask used in the <function><link linkend="API-devm-kmalloc">devm_kmalloc</link></function> call when
     allocating memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The <function>printf</function>-style format string
     @...: Arguments for the format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to allocated string on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-kfree">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_kfree</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_kfree</refname>
 <refpurpose>
     Resource-managed kfree
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>devm_kfree </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device this memory belongs to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     Memory to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free memory allocated with <function><link linkend="API-devm-kmalloc">devm_kmalloc</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-kmemdup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_kmemdup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_kmemdup</refname>
 <refpurpose>
     Resource-managed kmemdup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>devm_kmemdup </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const void * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device this memory belongs to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     Memory region to duplicate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     Memory region length
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     GFP mask to use
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Duplicate region of a memory using resource managed kmalloc
</para>
</refsect1>
</refentry>

<refentry id="API-devm-get-free-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_get_free_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_get_free_pages</refname>
 <refpurpose>
     Resource-managed __get_free_pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>devm_get_free_pages </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>unsigned int <parameter>order</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to allocate memory for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     Allocation gfp flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>order</parameter></term>
   <listitem>
    <para>
     Allocation size is (1 &lt;&lt; order) pages
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Managed get_free_pages.  Memory allocated with this function is
   automatically freed on driver detach.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Address of allocated memory on success, 0 on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-free-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_free_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_free_pages</refname>
 <refpurpose>
     Resource-managed free_pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>devm_free_pages </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned long <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device this memory belongs to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Memory to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free memory allocated with <function><link linkend="API-devm-get-free-pages">devm_get_free_pages</link></function>. Unlike free_pages,
   there is no need to supply the <parameter>order</parameter>.
</para>
</refsect1>
</refentry>

     </sect1>

  </chapter>

  <chapter id="devdrivers">
     <title>Device drivers infrastructure</title>
     <sect1><title>The Basic Device Driver-Model Structures </title>
<!-- include/linux/device.h -->
<refentry id="API-struct-bus-type">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct bus_type</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct bus_type</refname>
 <refpurpose>
  The bus type of the device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct bus_type {
  const char * name;
  const char * dev_name;
  struct device * dev_root;
  struct device_attribute * dev_attrs;
  const struct attribute_group ** bus_groups;
  const struct attribute_group ** dev_groups;
  const struct attribute_group ** drv_groups;
  int (* match) (struct device *dev, struct device_driver *drv);
  int (* uevent) (struct device *dev, struct kobj_uevent_env *env);
  int (* probe) (struct device *dev);
  int (* remove) (struct device *dev);
  void (* shutdown) (struct device *dev);
  int (* online) (struct device *dev);
  int (* offline) (struct device *dev);
  int (* suspend) (struct device *dev, pm_message_t state);
  int (* resume) (struct device *dev);
  const struct dev_pm_ops * pm;
  const struct iommu_ops * iommu_ops;
  struct subsys_private * p;
  struct lock_class_key lock_key;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name</term>
      <listitem><para>
The name of the bus.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev_name</term>
      <listitem><para>
Used for subsystems to enumerate devices like (<quote>foo<constant>u</constant></quote>, dev-&gt;id).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev_root</term>
      <listitem><para>
Default device to use as the parent.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev_attrs</term>
      <listitem><para>
Default attributes of the devices on the bus.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus_groups</term>
      <listitem><para>
Default attributes of the bus.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev_groups</term>
      <listitem><para>
Default attributes of the devices on the bus.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>drv_groups</term>
      <listitem><para>
Default attributes of the device drivers on the bus.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>match</term>
      <listitem><para>
Called, perhaps multiple times, whenever a new device or driver
is added for this bus. It should return a nonzero value if the
given device can be handled by the given driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>uevent</term>
      <listitem><para>
Called when a device is added, removed, or a few other things
that generate uevents to add the environment variables.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>probe</term>
      <listitem><para>
Called when a new device or driver add to this bus, and callback
the specific driver's probe to initial the matched device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>remove</term>
      <listitem><para>
Called when a device removed from this bus.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>shutdown</term>
      <listitem><para>
Called at shut-down time to quiesce the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>online</term>
      <listitem><para>
Called to put the device back online (after offlining it).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>offline</term>
      <listitem><para>
Called to put the device offline for hot-removal. May fail.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>suspend</term>
      <listitem><para>
Called when a device on this bus wants to go to sleep mode.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>resume</term>
      <listitem><para>
Called to bring a device on this bus out of sleep mode.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pm</term>
      <listitem><para>
Power management operations of this bus, callback the specific
device driver's pm-ops.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>iommu_ops</term>
      <listitem><para>
IOMMU specific operations for this bus, used to attach IOMMU
driver implementations to a bus and allow the driver to do
bus-specific setup
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p</term>
      <listitem><para>
The private data of the driver core, only the driver core can
touch this.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock_key</term>
      <listitem><para>
Lock class key for use by the lock validator
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   A bus is a channel between the processor and one or more devices. For the
   purposes of the device model, all devices are connected via a bus, even if
   it is an internal, virtual, <quote>platform</quote> bus. Buses can plug into each other.
   A USB controller is usually a PCI device, for example. The device model
   represents the actual connections between buses and the devices they control.
   A bus is represented by the bus_type structure. It contains the name, the
   default attributes, the bus' methods, PM operations, and the driver core's
   private data.
</para>
</refsect1>
</refentry>

<refentry id="API-enum-probe-type">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum probe_type</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum probe_type</refname>
 <refpurpose>
     device driver probe type to try Device drivers may opt in for special handling of their respective probe routines. This tells the core what to expect and prefer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum probe_type {
  PROBE_DEFAULT_STRATEGY,
  PROBE_PREFER_ASYNCHRONOUS,
  PROBE_FORCE_SYNCHRONOUS
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>PROBE_DEFAULT_STRATEGY</term>
      <listitem><para>
   Used by drivers that work equally well
   whether probed synchronously or asynchronously.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>PROBE_PREFER_ASYNCHRONOUS</term>
      <listitem><para>
   Drivers for <quote>slow</quote> devices which
   probing order is not essential for booting the system may
   opt into executing their probes asynchronously.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>PROBE_FORCE_SYNCHRONOUS</term>
      <listitem><para>
   Use this to annotate drivers that need
   their probe routines to run synchronously with driver and
   device registration (with the exception of -EPROBE_DEFER
   handling - re-probing always ends up being done asynchronously).
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that the end goal is to switch the kernel to use asynchronous
   probing by default, so annotating drivers with
   <constant>PROBE_PREFER_ASYNCHRONOUS</constant> is a temporary measure that allows us
   to speed up boot process while we are validating the rest of the
   drivers.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-device-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct device_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct device_driver</refname>
 <refpurpose>
     The basic device driver structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct device_driver {
  const char * name;
  struct bus_type * bus;
  struct module * owner;
  const char * mod_name;
  bool suppress_bind_attrs;
  enum probe_type probe_type;
  const struct of_device_id * of_match_table;
  const struct acpi_device_id * acpi_match_table;
  int (* probe) (struct device *dev);
  int (* remove) (struct device *dev);
  void (* shutdown) (struct device *dev);
  int (* suspend) (struct device *dev, pm_message_t state);
  int (* resume) (struct device *dev);
  const struct attribute_group ** groups;
  const struct dev_pm_ops * pm;
  struct driver_private * p;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name</term>
      <listitem><para>
   Name of the device driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus</term>
      <listitem><para>
   The bus which the device of this driver belongs to.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>owner</term>
      <listitem><para>
   The module owner.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mod_name</term>
      <listitem><para>
   Used for built-in modules.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>suppress_bind_attrs</term>
      <listitem><para>
   Disables bind/unbind via sysfs.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>probe_type</term>
      <listitem><para>
   Type of the probe (synchronous or asynchronous) to use.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>of_match_table</term>
      <listitem><para>
   The open firmware table.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>acpi_match_table</term>
      <listitem><para>
   The ACPI match table.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>probe</term>
      <listitem><para>
   Called to query the existence of a specific device,
   whether this driver can work with it, and bind the driver
   to a specific device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>remove</term>
      <listitem><para>
   Called when the device is removed from the system to
   unbind a device from this driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>shutdown</term>
      <listitem><para>
   Called at shut-down time to quiesce the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>suspend</term>
      <listitem><para>
   Called to put the device to sleep mode. Usually to a
   low power state.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>resume</term>
      <listitem><para>
   Called to bring a device from sleep mode.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>groups</term>
      <listitem><para>
   Default attributes that get created by the driver core
   automatically.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pm</term>
      <listitem><para>
   Power management operations of the device which matched
   this driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p</term>
      <listitem><para>
   Driver core's private data, no one other than the driver
   core can touch this.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   The device driver-model tracks all of the drivers known to the system.
   The main reason for this tracking is to enable the driver core to match
   up drivers with new devices. Once drivers are known objects within the
   system, however, a number of other things become possible. Device drivers
   can export information and configuration variables that are independent
   of any specific device.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-subsys-interface">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct subsys_interface</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct subsys_interface</refname>
 <refpurpose>
     interfaces to device functions
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct subsys_interface {
  const char * name;
  struct bus_type * subsys;
  struct list_head node;
  int (* add_dev) (struct device *dev, struct subsys_interface *sif);
  void (* remove_dev) (struct device *dev, struct subsys_interface *sif);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name</term>
      <listitem><para>
   name of the device function
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>subsys</term>
      <listitem><para>
   subsytem of the devices to attach to
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>node</term>
      <listitem><para>
   the list of functions registered at the subsystem
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>add_dev</term>
      <listitem><para>
   device hookup to device function handler
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>remove_dev</term>
      <listitem><para>
   device hookup to device function handler
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Simple interfaces attached to a subsystem. Multiple interfaces can
   attach to a subsystem and its devices. Unlike drivers, they do not
   exclusively claim or control devices. Interfaces usually represent
   a specific functionality of a subsystem/class of devices.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-class">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct class</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct class</refname>
 <refpurpose>
     device classes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct class {
  const char * name;
  struct module * owner;
  struct class_attribute * class_attrs;
  const struct attribute_group ** dev_groups;
  struct kobject * dev_kobj;
  int (* dev_uevent) (struct device *dev, struct kobj_uevent_env *env);
  char *(* devnode) (struct device *dev, umode_t *mode);
  void (* class_release) (struct class *class);
  void (* dev_release) (struct device *dev);
  int (* suspend) (struct device *dev, pm_message_t state);
  int (* resume) (struct device *dev);
  const struct kobj_ns_type_operations * ns_type;
  const void *(* namespace) (struct device *dev);
  const struct dev_pm_ops * pm;
  struct subsys_private * p;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name</term>
      <listitem><para>
   Name of the class.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>owner</term>
      <listitem><para>
   The module owner.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>class_attrs</term>
      <listitem><para>
   Default attributes of this class.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev_groups</term>
      <listitem><para>
   Default attributes of the devices that belong to the class.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev_kobj</term>
      <listitem><para>
   The kobject that represents this class and links it into the hierarchy.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev_uevent</term>
      <listitem><para>
   Called when a device is added, removed from this class, or a
   few other things that generate uevents to add the environment
   variables.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>devnode</term>
      <listitem><para>
   Callback to provide the devtmpfs.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>class_release</term>
      <listitem><para>
   Called to release this class.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev_release</term>
      <listitem><para>
   Called to release the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>suspend</term>
      <listitem><para>
   Used to put the device to sleep mode, usually to a low power
   state.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>resume</term>
      <listitem><para>
   Used to bring the device from the sleep mode.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ns_type</term>
      <listitem><para>
   Callbacks so sysfs can detemine namespaces.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>namespace</term>
      <listitem><para>
   Namespace of the device belongs to this class.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pm</term>
      <listitem><para>
   The default device power management operations of this class.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p</term>
      <listitem><para>
   The private data of the driver core, no one other than the
   driver core can touch this.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   A class is a higher-level view of a device that abstracts out low-level
   implementation details. Drivers may see a SCSI disk or an ATA disk, but,
   at the class level, they are all simply disks. Classes allow user space
   to work with devices based on what they do, rather than how they are
   connected or how they work.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct device</refname>
 <refpurpose>
     The basic device structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct device {
  struct device * parent;
  struct device_private * p;
  struct kobject kobj;
  const char * init_name;
  const struct device_type * type;
  struct mutex mutex;
  struct bus_type * bus;
  struct device_driver * driver;
  void * platform_data;
  void * driver_data;
  struct dev_pm_info power;
  struct dev_pm_domain * pm_domain;
#ifdef CONFIG_GENERIC_MSI_IRQ_DOMAIN
  struct irq_domain * msi_domain;
#endif
#ifdef CONFIG_PINCTRL
  struct dev_pin_info * pins;
#endif
#ifdef CONFIG_GENERIC_MSI_IRQ
  struct list_head msi_list;
#endif
#ifdef CONFIG_NUMA
  int numa_node;
#endif
  u64 * dma_mask;
  u64 coherent_dma_mask;
  unsigned long dma_pfn_offset;
  struct device_dma_parameters * dma_parms;
  struct list_head dma_pools;
  struct dma_coherent_mem * dma_mem;
#ifdef CONFIG_DMA_CMA
  struct cma * cma_area;
#endif
  struct dev_archdata archdata;
  struct device_node * of_node;
  struct fwnode_handle * fwnode;
  dev_t devt;
  u32 id;
  spinlock_t devres_lock;
  struct list_head devres_head;
  struct klist_node knode_class;
  struct class * class;
  const struct attribute_group ** groups;
  void (* release) (struct device *dev);
  struct iommu_group * iommu_group;
  bool offline_disabled:1;
  bool offline:1;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>parent</term>
      <listitem><para>
   The device's <quote>parent</quote> device, the device to which it is attached.
   In most cases, a parent device is some sort of bus or host
   controller. If parent is NULL, the device, is a top-level device,
   which is not usually what you want.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p</term>
      <listitem><para>
   Holds the private data of the driver core portions of the device.
   See the comment of the struct device_private for detail.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>kobj</term>
      <listitem><para>
   A top-level, abstract class from which other classes are derived.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>init_name</term>
      <listitem><para>
   Initial name of the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type</term>
      <listitem><para>
   The type of device.
   This identifies the device type and carries type-specific
   information.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mutex</term>
      <listitem><para>
   Mutex to synchronize calls to its driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus</term>
      <listitem><para>
   Type of bus device is on.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver</term>
      <listitem><para>
   Which driver has allocated this
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>platform_data</term>
      <listitem><para>
   Platform data specific to the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver_data</term>
      <listitem><para>
   Private pointer for driver specific info.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>power</term>
      <listitem><para>
   For device power management.
   See Documentation/power/devices.txt for details.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pm_domain</term>
      <listitem><para>
   Provide callbacks that are executed during system suspend,
   hibernation, system resume and during runtime PM transitions
   along with subsystem-level and driver-level callbacks.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>msi_domain</term>
      <listitem><para>
   The generic MSI domain this device is using.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pins</term>
      <listitem><para>
   For device pin management.
   See Documentation/pinctrl.txt for details.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>msi_list</term>
      <listitem><para>
   Hosts MSI descriptors
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>numa_node</term>
      <listitem><para>
   NUMA node this device is close to.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dma_mask</term>
      <listitem><para>
   Dma mask (if dma'ble device).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>coherent_dma_mask</term>
      <listitem><para>
   Like dma_mask, but for alloc_coherent mapping as not all
   hardware supports 64-bit addresses for consistent allocations
   such descriptors.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dma_pfn_offset</term>
      <listitem><para>
   offset of DMA memory range relatively of RAM
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dma_parms</term>
      <listitem><para>
   A low level driver may set these to teach IOMMU code about
   segment limitations.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dma_pools</term>
      <listitem><para>
   Dma pools (if dma'ble device).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dma_mem</term>
      <listitem><para>
   Internal for coherent mem override.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cma_area</term>
      <listitem><para>
   Contiguous memory area for dma allocations
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>archdata</term>
      <listitem><para>
   For arch-specific additions.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>of_node</term>
      <listitem><para>
   Associated device tree node.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fwnode</term>
      <listitem><para>
   Associated device node supplied by platform firmware.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>devt</term>
      <listitem><para>
   For creating the sysfs <quote>dev</quote>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id</term>
      <listitem><para>
   device instance
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>devres_lock</term>
      <listitem><para>
   Spinlock to protect the resource of the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>devres_head</term>
      <listitem><para>
   The resources list of the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>knode_class</term>
      <listitem><para>
   The node used to add the device to the class list.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>class</term>
      <listitem><para>
   The class of the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>groups</term>
      <listitem><para>
   Optional attribute groups.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release</term>
      <listitem><para>
   Callback to free the device after all references have
   gone away. This should be set by the allocator of the
   device (i.e. the bus driver that discovered the device).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>iommu_group</term>
      <listitem><para>
   IOMMU group the device belongs to.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>offline_disabled</term>
      <listitem><para>
   If set, the device is permanently online.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>offline</term>
      <listitem><para>
   Set after successful invocation of bus type's .<function>offline</function>.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Example</title>
<informalexample><programlisting>
   For devices on custom boards, as typical of embedded
   		and SOC based hardware, Linux often uses platform_data to point
   		to board-specific structures describing devices and how they
   		are wired.  That can include what ports are available, chip
   		variants, which GPIO pins act in what additional roles, and so
   		on.  This shrinks the <quote>Board Support Packages</quote> (BSPs) and
   		minimizes board-specific #ifdefs in drivers.
</programlisting></informalexample>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   At the lowest level, every device in a Linux system is represented by an
   instance of struct device. The device structure contains the information
   that the device model core needs to model the system. Most subsystems,
   however, track additional information about the devices they host. As a
   result, it is rare for devices to be represented by bare device structures;
   instead, that structure, like kobject structures, is usually embedded within
   a higher-level representation of the device.
</para>
</refsect1>
</refentry>

<refentry id="API-module-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>module_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>module_driver</refname>
 <refpurpose>
     Helper macro for drivers that don't do anything special in module init/exit. This eliminates a lot of boilerplate. Each module may only use this macro once, and calling it replaces <function>module_init</function> and <function>module_exit</function>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>module_driver </function></funcdef>
   <paramdef> <parameter>__driver</parameter></paramdef>
   <paramdef> <parameter>__register</parameter></paramdef>
   <paramdef> <parameter>__unregister</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>__driver</parameter></term>
   <listitem>
    <para>
     driver name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>__register</parameter></term>
   <listitem>
    <para>
     register function for this driver type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>__unregister</parameter></term>
   <listitem>
    <para>
     unregister function for this driver type
     @...: Additional arguments to be passed to __register and __unregister.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use this macro to construct bus specific macros for registering
   drivers, and do not use it on its own.
</para>
</refsect1>
</refentry>

<refentry id="API-builtin-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>builtin_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>builtin_driver</refname>
 <refpurpose>
     Helper macro for drivers that don't do anything special in init and have no exit. This eliminates some boilerplate. Each driver may only use this macro once, and calling it replaces device_initcall (or in some cases, the legacy __initcall). This is meant to be a direct parallel of <function><link linkend="API-module-driver">module_driver</link></function> above but without the __exit stuff that is not used for builtin cases.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>builtin_driver </function></funcdef>
   <paramdef> <parameter>__driver</parameter></paramdef>
   <paramdef> <parameter>__register</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>__driver</parameter></term>
   <listitem>
    <para>
     driver name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>__register</parameter></term>
   <listitem>
    <para>
     register function for this driver type
     @...: Additional arguments to be passed to __register
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use this macro to construct bus specific macros for registering
   drivers, and do not use it on its own.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Device Drivers Base</title>
<!-- drivers/base/init.c -->
<refentry id="API-driver-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>driver_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>driver_init</refname>
 <refpurpose>
  initialize driver model.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>driver_init </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Call the driver model init functions to initialize their
   subsystems. Called early from init/main.c.
</para>
</refsect1>
</refentry>

<!-- drivers/base/driver.c -->
<refentry id="API-driver-for-each-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>driver_for_each_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>driver_for_each_device</refname>
 <refpurpose>
  Iterator for devices bound to a driver.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>driver_for_each_device </function></funcdef>
   <paramdef><link linkend="API-struct-device-driver">struct device_driver</link> * <parameter>drv</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>start</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>fn</parameter>)
     <funcparams>struct device *, void *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     Driver we're iterating.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Device to begin with
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     Data to pass to the callback.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     Function to call for each device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over the <parameter>drv</parameter>'s list of devices calling <parameter>fn</parameter> for each one.
</para>
</refsect1>
</refentry>

<refentry id="API-driver-find-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>driver_find_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>driver_find_device</refname>
 <refpurpose>
     device iterator for locating a particular device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>driver_find_device </function></funcdef>
   <paramdef><link linkend="API-struct-device-driver">struct device_driver</link> * <parameter>drv</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>start</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>match</parameter>)
     <funcparams>struct device *dev, void *data</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     The device's driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Device to begin with
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     Data to pass to match function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match</parameter></term>
   <listitem>
    <para>
     Callback function to check device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is similar to the <function><link linkend="API-driver-for-each-device">driver_for_each_device</link></function> function above, but
   it returns a reference to a device that is 'found' for later use, as
   determined by the <parameter>match</parameter> callback.
   </para><para>

   The callback should return 0 if the device doesn't match and non-zero
   if it does.  If the callback returns non-zero, this function will
   return to the caller and not iterate over any more devices.
</para>
</refsect1>
</refentry>

<refentry id="API-driver-create-file">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>driver_create_file</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>driver_create_file</refname>
 <refpurpose>
     create sysfs file for driver.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>driver_create_file </function></funcdef>
   <paramdef><link linkend="API-struct-device-driver">struct device_driver</link> * <parameter>drv</parameter></paramdef>
   <paramdef>const struct driver_attribute * <parameter>attr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     driver.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     driver attribute descriptor.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-driver-remove-file">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>driver_remove_file</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>driver_remove_file</refname>
 <refpurpose>
     remove sysfs file for driver.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>driver_remove_file </function></funcdef>
   <paramdef><link linkend="API-struct-device-driver">struct device_driver</link> * <parameter>drv</parameter></paramdef>
   <paramdef>const struct driver_attribute * <parameter>attr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     driver.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     driver attribute descriptor.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-driver-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>driver_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>driver_register</refname>
 <refpurpose>
     register driver with bus
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>driver_register </function></funcdef>
   <paramdef><link linkend="API-struct-device-driver">struct device_driver</link> * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     driver to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   We pass off most of the work to the <function>bus_add_driver</function> call,
   since most of the things we have to do deal with the bus
   structures.
</para>
</refsect1>
</refentry>

<refentry id="API-driver-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>driver_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>driver_unregister</refname>
 <refpurpose>
     remove driver from system.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>driver_unregister </function></funcdef>
   <paramdef><link linkend="API-struct-device-driver">struct device_driver</link> * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     driver.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Again, we pass off most of the work to the bus-level call.
</para>
</refsect1>
</refentry>

<refentry id="API-driver-find">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>driver_find</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>driver_find</refname>
 <refpurpose>
     locate driver on a bus by its name.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device-driver">struct device_driver</link> * <function>driver_find </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>bus</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of the driver.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     bus to scan for the driver.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Call <function>kset_find_obj</function> to iterate over list of drivers on
   a bus to find driver by name. Return driver if found.
   </para><para>

   This routine provides no locking to prevent the driver it returns
   from being unregistered or unloaded while the caller is using it.
   The caller is responsible for preventing this.
</para>
</refsect1>
</refentry>

<!-- drivers/base/core.c -->
<refentry id="API-dev-driver-string">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_driver_string</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_driver_string</refname>
 <refpurpose>
  Return a device's driver name, if at all possible
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>dev_driver_string </function></funcdef>
   <paramdef><link linkend="API-struct-device">const struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     struct device to get the name of
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Will return the device's driver's name if it is bound to a device.  If
   the device is not bound to a driver, it will return the name of the bus
   it is attached to.  If it is not attached to a bus either, an empty
   string will be returned.
</para>
</refsect1>
</refentry>

<refentry id="API-device-create-file">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_create_file</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_create_file</refname>
 <refpurpose>
     create sysfs attribute file for device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_create_file </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const struct device_attribute * <parameter>attr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     device attribute descriptor.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-device-remove-file">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_remove_file</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_remove_file</refname>
 <refpurpose>
     remove sysfs attribute file.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>device_remove_file </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const struct device_attribute * <parameter>attr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     device attribute descriptor.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-device-remove-file-self">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_remove_file_self</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_remove_file_self</refname>
 <refpurpose>
     remove sysfs attribute file from its own method.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>device_remove_file_self </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const struct device_attribute * <parameter>attr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     device attribute descriptor.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   See <function>kernfs_remove_self</function> for details.
</para>
</refsect1>
</refentry>

<refentry id="API-device-create-bin-file">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_create_bin_file</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_create_bin_file</refname>
 <refpurpose>
     create sysfs binary attribute file for device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_create_bin_file </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const struct bin_attribute * <parameter>attr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     device binary attribute descriptor.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-device-remove-bin-file">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_remove_bin_file</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_remove_bin_file</refname>
 <refpurpose>
     remove sysfs binary attribute file
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>device_remove_bin_file </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const struct bin_attribute * <parameter>attr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     device binary attribute descriptor.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-device-initialize">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_initialize</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_initialize</refname>
 <refpurpose>
     init device structure.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>device_initialize </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This prepares the device for use by other layers by initializing
   its fields.
   It is the first half of <function><link linkend="API-device-register">device_register</link></function>, if called by
   that function, though it can also be called separately, so one
   may use <parameter>dev</parameter>'s fields. In particular, <function><link linkend="API-get-device">get_device</link></function>/<function><link linkend="API-put-device">put_device</link></function>
   may be used for reference counting of <parameter>dev</parameter> after calling this
   function.
   </para><para>

   All fields in <parameter>dev</parameter> must be initialized by the caller to 0, except
   for those explicitly set to some other value.  The simplest
   approach is to use <function>kzalloc</function> to allocate the structure containing
   <parameter>dev</parameter>.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   Use <function><link linkend="API-put-device">put_device</link></function> to give up your reference instead of freeing
   <parameter>dev</parameter> directly once you have called this function.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-set-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_set_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_set_name</refname>
 <refpurpose>
     set a device name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dev_set_name </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string for the device's name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-device-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_add</refname>
 <refpurpose>
     add device to device hierarchy.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_add </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is part 2 of <function><link linkend="API-device-register">device_register</link></function>, though may be called
   separately _iff_ <function><link linkend="API-device-initialize">device_initialize</link></function> has been called separately.
   </para><para>

   This adds <parameter>dev</parameter> to the kobject hierarchy via <function><link linkend="API-kobject-add">kobject_add</link></function>, adds it
   to the global and sibling lists for the device, then
   adds it to the other relevant subsystems of the driver model.
   </para><para>

   Do not call this routine or <function><link linkend="API-device-register">device_register</link></function> more than once for
   any device structure.  The driver model core is not designed to work
   with devices that get unregistered and then spring back to life.
   (Among other things, it's very hard to guarantee that all references
   to the previous incarnation of <parameter>dev</parameter> have been dropped.)  Allocate
   and register a fresh new struct device instead.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   _Never_ directly free <parameter>dev</parameter> after calling this function, even
   if it returned an error! Always use <function><link linkend="API-put-device">put_device</link></function> to give up your
   reference instead.
</para>
</refsect1>
</refentry>

<refentry id="API-device-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_register</refname>
 <refpurpose>
     register a device with the system.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_register </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the device structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This happens in two clean steps - initialize the device
   and add it to the system. The two steps can be called
   separately, but this is the easiest and most common.
   I.e. you should only call the two helpers separately if
   have a clearly defined need to use and refcount the device
   before it is added to the hierarchy.
   </para><para>

   For more information, see the kerneldoc for <function><link linkend="API-device-initialize">device_initialize</link></function>
   and <function><link linkend="API-device-add">device_add</link></function>.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   _Never_ directly free <parameter>dev</parameter> after calling this function, even
   if it returned an error! Always use <function><link linkend="API-put-device">put_device</link></function> to give up the
   reference initialized in this function instead.
</para>
</refsect1>
</refentry>

<refentry id="API-get-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_device</refname>
 <refpurpose>
     increment reference count for device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>get_device </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This simply forwards the call to <function><link linkend="API-kobject-get">kobject_get</link></function>, though
   we do take care to provide for the case that we get a NULL
   pointer passed in.
</para>
</refsect1>
</refentry>

<refentry id="API-put-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>put_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>put_device</refname>
 <refpurpose>
     decrement reference count.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>put_device </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device in question.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-device-del">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_del</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_del</refname>
 <refpurpose>
     delete device from system.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>device_del </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the first part of the device unregistration
   sequence. This removes the device from the lists we control
   from here, has it removed from the other driver model
   subsystems it was added to in <function><link linkend="API-device-add">device_add</link></function>, and removes it
   from the kobject hierarchy.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   this should be called manually _iff_ <function><link linkend="API-device-add">device_add</link></function> was
   also called manually.
</para>
</refsect1>
</refentry>

<refentry id="API-device-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_unregister</refname>
 <refpurpose>
     unregister device from system.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>device_unregister </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device going away.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   We do this in two parts, like we do <function><link linkend="API-device-register">device_register</link></function>. First,
   we remove it from all the subsystems with <function><link linkend="API-device-del">device_del</link></function>, then
   we decrement the reference count via <function><link linkend="API-put-device">put_device</link></function>. If that
   is the final reference count, the device will be cleaned up
   via <function>device_release</function> above. Otherwise, the structure will
   stick around until the final reference to the device is dropped.
</para>
</refsect1>
</refentry>

<refentry id="API-device-for-each-child">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_for_each_child</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_for_each_child</refname>
 <refpurpose>
     device child iterator.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_for_each_child </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>parent</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>fn</parameter>)
     <funcparams>struct device *dev, void *data</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent struct device.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data for the callback.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     function to be called for each device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over <parameter>parent</parameter>'s child devices, and call <parameter>fn</parameter> for each,
   passing it <parameter>data</parameter>.
   </para><para>

   We check the return of <parameter>fn</parameter> each time. If it returns anything
   other than 0, we break out and return that value.
</para>
</refsect1>
</refentry>

<refentry id="API-device-for-each-child-reverse">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_for_each_child_reverse</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_for_each_child_reverse</refname>
 <refpurpose>
     device child iterator in reversed order.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_for_each_child_reverse </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>parent</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>fn</parameter>)
     <funcparams>struct device *dev, void *data</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent struct device.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data for the callback.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     function to be called for each device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over <parameter>parent</parameter>'s child devices, and call <parameter>fn</parameter> for each,
   passing it <parameter>data</parameter>.
   </para><para>

   We check the return of <parameter>fn</parameter> each time. If it returns anything
   other than 0, we break out and return that value.
</para>
</refsect1>
</refentry>

<refentry id="API-device-find-child">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_find_child</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_find_child</refname>
 <refpurpose>
     device iterator for locating a particular device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>device_find_child </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>parent</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>match</parameter>)
     <funcparams>struct device *dev, void *data</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent struct device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     Data to pass to match function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match</parameter></term>
   <listitem>
    <para>
     Callback function to check device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is similar to the <function><link linkend="API-device-for-each-child">device_for_each_child</link></function> function above, but it
   returns a reference to a device that is 'found' for later use, as
   determined by the <parameter>match</parameter> callback.
   </para><para>

   The callback should return 0 if the device doesn't match and non-zero
   if it does.  If the callback returns non-zero and a reference to the
   current device can be obtained, this function will return to the caller
   and not iterate over any more devices.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   you will need to drop the reference with <function><link linkend="API-put-device">put_device</link></function> after use.
</para>
</refsect1>
</refentry>

<refentry id="API---root-device-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__root_device_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__root_device_register</refname>
 <refpurpose>
     allocate and register a root device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>__root_device_register </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     root device name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     owner module of the root device, usually THIS_MODULE
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function allocates a root device and registers it
   using <function><link linkend="API-device-register">device_register</link></function>. In order to free the returned
   device, use <function><link linkend="API-root-device-unregister">root_device_unregister</link></function>.
   </para><para>

   Root devices are dummy devices which allow other devices
   to be grouped under /sys/devices. Use this function to
   allocate a root device and then use it as the parent of
   any device which should appear under /sys/devices/{name}
   </para><para>

   The /sys/devices/{name} directory will also contain a
   'module' symlink which points to the <parameter>owner</parameter> directory
   in sysfs.
   </para><para>

   Returns <structname><link linkend="API-struct-device">struct device</link></structname> pointer on success, or <function>ERR_PTR</function> on error.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   You probably want to use <function>root_device_register</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-root-device-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>root_device_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>root_device_unregister</refname>
 <refpurpose>
     unregister and free a root device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>root_device_unregister </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device going away
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function unregisters and cleans up a device that was created by
   <function>root_device_register</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-device-create-vargs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_create_vargs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_create_vargs</refname>
 <refpurpose>
     creates a device and registers it with sysfs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>device_create_vargs </function></funcdef>
   <paramdef><link linkend="API-struct-class">struct class</link> * <parameter>class</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>parent</parameter></paramdef>
   <paramdef>dev_t <parameter>devt</parameter></paramdef>
   <paramdef>void * <parameter>drvdata</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef>va_list <parameter>args</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>class</parameter></term>
   <listitem>
    <para>
     pointer to the struct class that this device should be registered to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     pointer to the parent struct device of this new device, if any
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devt</parameter></term>
   <listitem>
    <para>
     the dev_t for the char device to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drvdata</parameter></term>
   <listitem>
    <para>
     the data to be added to the device for callbacks
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     string for the device's name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args</parameter></term>
   <listitem>
    <para>
     va_list for the device's name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can be used by char device classes.  A struct device
   will be created in sysfs, registered to the specified class.
   </para><para>

   A <quote>dev</quote> file will be created, showing the dev_t for the device, if
   the dev_t is not 0,0.
   If a pointer to a parent struct device is passed in, the newly created
   struct device will be a child of that device in sysfs.
   The pointer to the struct device will be returned from the call.
   Any further sysfs files that might be required can be created using this
   pointer.
   </para><para>

   Returns <structname><link linkend="API-struct-device">struct device</link></structname> pointer on success, or <function>ERR_PTR</function> on error.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the struct class passed to this function must have previously
   been created with a call to <function>class_create</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-device-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_create</refname>
 <refpurpose>
     creates a device and registers it with sysfs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>device_create </function></funcdef>
   <paramdef><link linkend="API-struct-class">struct class</link> * <parameter>class</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>parent</parameter></paramdef>
   <paramdef>dev_t <parameter>devt</parameter></paramdef>
   <paramdef>void * <parameter>drvdata</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>class</parameter></term>
   <listitem>
    <para>
     pointer to the struct class that this device should be registered to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     pointer to the parent struct device of this new device, if any
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devt</parameter></term>
   <listitem>
    <para>
     the dev_t for the char device to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drvdata</parameter></term>
   <listitem>
    <para>
     the data to be added to the device for callbacks
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     string for the device's name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can be used by char device classes.  A struct device
   will be created in sysfs, registered to the specified class.
   </para><para>

   A <quote>dev</quote> file will be created, showing the dev_t for the device, if
   the dev_t is not 0,0.
   If a pointer to a parent struct device is passed in, the newly created
   struct device will be a child of that device in sysfs.
   The pointer to the struct device will be returned from the call.
   Any further sysfs files that might be required can be created using this
   pointer.
   </para><para>

   Returns <structname><link linkend="API-struct-device">struct device</link></structname> pointer on success, or <function>ERR_PTR</function> on error.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the struct class passed to this function must have previously
   been created with a call to <function>class_create</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-device-create-with-groups">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_create_with_groups</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_create_with_groups</refname>
 <refpurpose>
     creates a device and registers it with sysfs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>device_create_with_groups </function></funcdef>
   <paramdef><link linkend="API-struct-class">struct class</link> * <parameter>class</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>parent</parameter></paramdef>
   <paramdef>dev_t <parameter>devt</parameter></paramdef>
   <paramdef>void * <parameter>drvdata</parameter></paramdef>
   <paramdef>const struct attribute_group ** <parameter>groups</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>class</parameter></term>
   <listitem>
    <para>
     pointer to the struct class that this device should be registered to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     pointer to the parent struct device of this new device, if any
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devt</parameter></term>
   <listitem>
    <para>
     the dev_t for the char device to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drvdata</parameter></term>
   <listitem>
    <para>
     the data to be added to the device for callbacks
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>groups</parameter></term>
   <listitem>
    <para>
     NULL-terminated list of attribute groups to be created
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     string for the device's name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can be used by char device classes.  A struct device
   will be created in sysfs, registered to the specified class.
   Additional attributes specified in the groups parameter will also
   be created automatically.
   </para><para>

   A <quote>dev</quote> file will be created, showing the dev_t for the device, if
   the dev_t is not 0,0.
   If a pointer to a parent struct device is passed in, the newly created
   struct device will be a child of that device in sysfs.
   The pointer to the struct device will be returned from the call.
   Any further sysfs files that might be required can be created using this
   pointer.
   </para><para>

   Returns <structname><link linkend="API-struct-device">struct device</link></structname> pointer on success, or <function>ERR_PTR</function> on error.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the struct class passed to this function must have previously
   been created with a call to <function>class_create</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-device-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_destroy</refname>
 <refpurpose>
     removes a device that was created with <function><link linkend="API-device-create">device_create</link></function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>device_destroy </function></funcdef>
   <paramdef><link linkend="API-struct-class">struct class</link> * <parameter>class</parameter></paramdef>
   <paramdef>dev_t <parameter>devt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>class</parameter></term>
   <listitem>
    <para>
     pointer to the struct class that this device was registered with
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devt</parameter></term>
   <listitem>
    <para>
     the dev_t of the device that was previously registered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call unregisters and cleans up a device that was created with a
   call to <function><link linkend="API-device-create">device_create</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-device-rename">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_rename</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_rename</refname>
 <refpurpose>
     renames a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_rename </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const char * <parameter>new_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the pointer to the struct device to be renamed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_name</parameter></term>
   <listitem>
    <para>
     the new name of the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It is the responsibility of the caller to provide mutual
   exclusion between two different calls of device_rename
   on the same device to ensure that new_name is valid and
   won't conflict with other devices.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   Don't call this function.  Currently, the networking layer calls this
   function, but that will change.  The following text from Kay Sievers offers
</para>
</refsect1>
<refsect1>
<title>some insight</title>
<para>
   </para><para>

   Renaming devices is racy at many levels, symlinks and other stuff are not
   replaced atomically, and you get a <quote>move</quote> uevent, but it's not easy to
   connect the event to the old and new device. Device nodes are not renamed at
   all, there isn't even support for that in the kernel now.
   </para><para>

   In the meantime, during renaming, your target name might be taken by another
   driver, creating conflicts. Or the old name is taken directly after you
   renamed it -- then you get events for the same DEVPATH, before you even see
   the <quote>move</quote> event. It's just a mess, and nothing new should ever rely on
   kernel device renaming. Besides that, it's not even implemented now for
   other things than (driver-core wise very simple) network devices.
   </para><para>

   We are currently about to change network renaming in udev to completely
   disallow renaming of devices in the same namespace as the kernel uses,
   because we can't solve the problems properly, that arise with swapping names
   of multiple interfaces without races. Means, renaming of eth[0-9]* will only
   be allowed to some other name than eth[0-9]*, for the aforementioned
   reasons.
   </para><para>

   Make up a <quote>real</quote> name in the driver before you register anything, or add
   some other attributes for userspace to find the device, or use udev to add
   symlinks -- but never rename kernel devices later, it's a complete mess. We
   don't even want to get into that and try to implement the missing pieces in
   the core. We really have other pieces to fix in the driver core mess. :)
</para>
</refsect1>
</refentry>

<refentry id="API-device-move">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_move</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_move</refname>
 <refpurpose>
     moves a device to a new parent
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_move </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>new_parent</parameter></paramdef>
   <paramdef>enum dpm_order <parameter>dpm_order</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the pointer to the struct device to be moved
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_parent</parameter></term>
   <listitem>
    <para>
     the new parent of the device (can by NULL)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dpm_order</parameter></term>
   <listitem>
    <para>
     how to reorder the dpm_list
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-set-primary-fwnode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>set_primary_fwnode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>set_primary_fwnode</refname>
 <refpurpose>
     Change the primary firmware node of a given device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>set_primary_fwnode </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>struct fwnode_handle * <parameter>fwnode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to handle.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fwnode</parameter></term>
   <listitem>
    <para>
     New primary firmware node of the device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set the device's firmware node pointer to <parameter>fwnode</parameter>, but if a secondary
   firmware node of the device is present, preserve it.
</para>
</refsect1>
</refentry>

<!-- drivers/base/syscore.c -->
<refentry id="API-register-syscore-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_syscore_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_syscore_ops</refname>
 <refpurpose>
  Register a set of system core operations.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>register_syscore_ops </function></funcdef>
   <paramdef>struct syscore_ops * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     System core operations to register.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-unregister-syscore-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_syscore_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_syscore_ops</refname>
 <refpurpose>
     Unregister a set of system core operations.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_syscore_ops </function></funcdef>
   <paramdef>struct syscore_ops * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     System core operations to unregister.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-syscore-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>syscore_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>syscore_suspend</refname>
 <refpurpose>
     Execute all the registered system core suspend callbacks.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>syscore_suspend </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   This function is executed with one CPU on-line and disabled interrupts.
</para>
</refsect1>
</refentry>

<refentry id="API-syscore-resume">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>syscore_resume</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>syscore_resume</refname>
 <refpurpose>
     Execute all the registered system core resume callbacks.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>syscore_resume </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   This function is executed with one CPU on-line and disabled interrupts.
</para>
</refsect1>
</refentry>

<!-- drivers/base/class.c -->
<refentry id="API---class-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__class_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__class_create</refname>
 <refpurpose>
  create a struct class structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-class">struct class</link> * <function>__class_create </function></funcdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct lock_class_key * <parameter>key</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     pointer to the module that is to <quote>own</quote> this struct class
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     pointer to a string for the name of this class.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>key</parameter></term>
   <listitem>
    <para>
     the lock_class_key for this class; used by mutex lock debugging
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is used to create a struct class pointer that can then be used
   in calls to <function><link linkend="API-device-create">device_create</link></function>.
   </para><para>

   Returns <structname><link linkend="API-struct-class">struct class</link></structname> pointer on success, or <function>ERR_PTR</function> on error.
   </para><para>

   Note, the pointer created here is to be destroyed when finished by
   making a call to <function><link linkend="API-class-destroy">class_destroy</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-class-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_destroy</refname>
 <refpurpose>
     destroys a struct class structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>class_destroy </function></funcdef>
   <paramdef><link linkend="API-struct-class">struct class</link> * <parameter>cls</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cls</parameter></term>
   <listitem>
    <para>
     pointer to the struct class that is to be destroyed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note, the pointer to be destroyed must have been created with a call
   to <function>class_create</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-class-dev-iter-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_dev_iter_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_dev_iter_init</refname>
 <refpurpose>
     initialize class device iterator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>class_dev_iter_init </function></funcdef>
   <paramdef>struct class_dev_iter * <parameter>iter</parameter></paramdef>
   <paramdef><link linkend="API-struct-class">struct class</link> * <parameter>class</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>start</parameter></paramdef>
   <paramdef>const struct device_type * <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>iter</parameter></term>
   <listitem>
    <para>
     class iterator to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>class</parameter></term>
   <listitem>
    <para>
     the class we wanna iterate over
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     the device to start iterating from, if any
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     device_type of the devices to iterate over, NULL for all
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize class iterator <parameter>iter</parameter> such that it iterates over devices
   of <parameter>class</parameter>.  If <parameter>start</parameter> is set, the list iteration will start there,
   otherwise if it is NULL, the iteration starts at the beginning of
   the list.
</para>
</refsect1>
</refentry>

<refentry id="API-class-dev-iter-next">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_dev_iter_next</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_dev_iter_next</refname>
 <refpurpose>
     iterate to the next device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>class_dev_iter_next </function></funcdef>
   <paramdef>struct class_dev_iter * <parameter>iter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>iter</parameter></term>
   <listitem>
    <para>
     class iterator to proceed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Proceed <parameter>iter</parameter> to the next device and return it.  Returns NULL if
   iteration is complete.
   </para><para>

   The returned device is referenced and won't be released till
   iterator is proceed to the next device or exited.  The caller is
   free to do whatever it wants to do with the device including
   calling back into class code.
</para>
</refsect1>
</refentry>

<refentry id="API-class-dev-iter-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_dev_iter_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_dev_iter_exit</refname>
 <refpurpose>
     finish iteration
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>class_dev_iter_exit </function></funcdef>
   <paramdef>struct class_dev_iter * <parameter>iter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>iter</parameter></term>
   <listitem>
    <para>
     class iterator to finish
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finish an iteration.  Always call this function after iteration is
   complete whether the iteration ran till the end or not.
</para>
</refsect1>
</refentry>

<refentry id="API-class-for-each-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_for_each_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_for_each_device</refname>
 <refpurpose>
     device iterator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>class_for_each_device </function></funcdef>
   <paramdef><link linkend="API-struct-class">struct class</link> * <parameter>class</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>start</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>fn</parameter>)
     <funcparams>struct device *, void *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>class</parameter></term>
   <listitem>
    <para>
     the class we're iterating
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     the device to start with in the list, if any.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data for the callback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     function to be called for each device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over <parameter>class</parameter>'s list of devices, and call <parameter>fn</parameter> for each,
   passing it <parameter>data</parameter>.  If <parameter>start</parameter> is set, the list iteration will start
   there, otherwise if it is NULL, the iteration starts at the
   beginning of the list.
   </para><para>

   We check the return of <parameter>fn</parameter> each time. If it returns anything
   other than 0, we break out and return that value.
   </para><para>

   <parameter>fn</parameter> is allowed to do anything including calling back into class
   code.  There's no locking restriction.
</para>
</refsect1>
</refentry>

<refentry id="API-class-find-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_find_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_find_device</refname>
 <refpurpose>
     device iterator for locating a particular device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>class_find_device </function></funcdef>
   <paramdef><link linkend="API-struct-class">struct class</link> * <parameter>class</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>start</parameter></paramdef>
   <paramdef>const void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>match</parameter>)
     <funcparams>struct device *, const void *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>class</parameter></term>
   <listitem>
    <para>
     the class we're iterating
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Device to begin with
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data for the match function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match</parameter></term>
   <listitem>
    <para>
     function to check device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is similar to the <function>class_for_each_dev</function> function above, but it
   returns a reference to a device that is 'found' for later use, as
   determined by the <parameter>match</parameter> callback.
   </para><para>

   The callback should return 0 if the device doesn't match and non-zero
   if it does.  If the callback returns non-zero, this function will
   return to the caller and not iterate over any more devices.
   </para><para>

   Note, you will need to drop the reference with <function><link linkend="API-put-device">put_device</link></function> after use.
   </para><para>

   <parameter>match</parameter> is allowed to do anything including calling back into class
   code.  There's no locking restriction.
</para>
</refsect1>
</refentry>

<refentry id="API-class-compat-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_compat_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_compat_register</refname>
 <refpurpose>
     register a compatibility class
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct class_compat * <function>class_compat_register </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the name of the class
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Compatibility class are meant as a temporary user-space compatibility
   workaround when converting a family of class devices to a bus devices.
</para>
</refsect1>
</refentry>

<refentry id="API-class-compat-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_compat_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_compat_unregister</refname>
 <refpurpose>
     unregister a compatibility class
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>class_compat_unregister </function></funcdef>
   <paramdef>struct class_compat * <parameter>cls</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cls</parameter></term>
   <listitem>
    <para>
     the class to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-class-compat-create-link">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_compat_create_link</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_compat_create_link</refname>
 <refpurpose>
     create a compatibility class device link to a bus device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>class_compat_create_link </function></funcdef>
   <paramdef>struct class_compat * <parameter>cls</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>device_link</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cls</parameter></term>
   <listitem>
    <para>
     the compatibility class
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the target bus device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device_link</parameter></term>
   <listitem>
    <para>
     an optional device to which a <quote>device</quote> link should be created
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-class-compat-remove-link">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_compat_remove_link</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_compat_remove_link</refname>
 <refpurpose>
     remove a compatibility class device link to a bus device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>class_compat_remove_link </function></funcdef>
   <paramdef>struct class_compat * <parameter>cls</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>device_link</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cls</parameter></term>
   <listitem>
    <para>
     the compatibility class
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the target bus device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device_link</parameter></term>
   <listitem>
    <para>
     an optional device to which a <quote>device</quote> link was previously
     created
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/base/node.c -->
<refentry id="API-unregister-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_node</refname>
 <refpurpose>
  unregister a node device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_node </function></funcdef>
   <paramdef>struct node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     node going away
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregisters a node device <parameter>node</parameter>.  All the devices on the node must be
   unregistered before calling this function.
</para>
</refsect1>
</refentry>

<!-- drivers/base/firmware_class.c -->
<refentry id="API-request-firmware">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_firmware</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>request_firmware</refname>
 <refpurpose>
  send firmware request and wait for it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>request_firmware </function></funcdef>
   <paramdef>const struct firmware ** <parameter>firmware_p</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>device</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>firmware_p</parameter></term>
   <listitem>
    <para>
     pointer to firmware image
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of firmware file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     device for which firmware is being loaded
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <parameter>firmware_p</parameter> will be used to return a firmware image by the name
   of <parameter>name</parameter> for device <parameter>device</parameter>.
   </para><para>

   Should be called from user context where sleeping is allowed.
   </para><para>

   <parameter>name</parameter> will be used as <envar>$FIRMWARE</envar> in the uevent environment and
   should be distinctive enough not to be confused with any other
   firmware image for this or any other device.
   </para><para>

   Caller must hold the reference count of <parameter>device</parameter>.
   </para><para>

   The function can be called safely inside device's suspend and
   resume callback.
</para>
</refsect1>
</refentry>

<refentry id="API-request-firmware-direct">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_firmware_direct</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>request_firmware_direct</refname>
 <refpurpose>
     load firmware directly without usermode helper
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>request_firmware_direct </function></funcdef>
   <paramdef>const struct firmware ** <parameter>firmware_p</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>device</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>firmware_p</parameter></term>
   <listitem>
    <para>
     pointer to firmware image
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of firmware file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     device for which firmware is being loaded
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function works pretty much like <function><link linkend="API-request-firmware">request_firmware</link></function>, but this doesn't
   fall back to usermode helper even if the firmware couldn't be loaded
   directly from fs.  Hence it's useful for loading optional firmwares, which
   aren't always present, without extra long timeouts of udev.
</para>
</refsect1>
</refentry>

<refentry id="API-release-firmware">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>release_firmware</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>release_firmware</refname>
 <refpurpose>
     release the resource associated with a firmware image
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>release_firmware </function></funcdef>
   <paramdef>const struct firmware * <parameter>fw</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fw</parameter></term>
   <listitem>
    <para>
     firmware resource to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-request-firmware-nowait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_firmware_nowait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>request_firmware_nowait</refname>
 <refpurpose>
     asynchronous version of request_firmware
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>request_firmware_nowait </function></funcdef>
   <paramdef>struct module * <parameter>module</parameter></paramdef>
   <paramdef>bool <parameter>uevent</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>device</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
   <paramdef>void * <parameter>context</parameter></paramdef>
   <paramdef>void (*<parameter>cont</parameter>)
     <funcparams>const struct firmware *fw, void *context</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>module</parameter></term>
   <listitem>
    <para>
     module requesting the firmware
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uevent</parameter></term>
   <listitem>
    <para>
     sends uevent to copy the firmware image if this flag
     is non-zero else the firmware copy must be done manually.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of firmware file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     device for which firmware is being loaded
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     allocation flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>context</parameter></term>
   <listitem>
    <para>
     will be passed over to <parameter>cont</parameter>, and
     <parameter>fw</parameter> may be <constant>NULL</constant> if firmware request fails.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cont</parameter></term>
   <listitem>
    <para>
     function will be called asynchronously when the firmware
     request is over.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Caller must hold the reference count of <parameter>device</parameter>.
   </para><para>

   Asynchronous variant of <function><link linkend="API-request-firmware">request_firmware</link></function> for user contexts:
   - sleep for as small periods as possible since it may
   increase kernel boot time of built-in device drivers
   requesting firmware in their -&gt;<function>probe</function> methods, if
   <parameter>gfp</parameter> is GFP_KERNEL.
   </para><para>

   - can't sleep at all if <parameter>gfp</parameter> is GFP_ATOMIC.
</para>
</refsect1>
</refentry>

<!-- drivers/base/transport_class.c -->
<refentry id="API-transport-class-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>transport_class_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>transport_class_register</refname>
 <refpurpose>
  register an initial transport class
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>transport_class_register </function></funcdef>
   <paramdef>struct transport_class * <parameter>tclass</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>tclass</parameter></term>
   <listitem>
    <para>
     a pointer to the transport class structure to be initialised
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The transport class contains an embedded class which is used to
   identify it.  The caller should initialise this structure with
   zeros and then generic class must have been initialised with the
   actual transport class unique name.  There's a macro
   <function>DECLARE_TRANSPORT_CLASS</function> to do this (declared classes still must
   be registered).
   </para><para>

   Returns 0 on success or error on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-transport-class-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>transport_class_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>transport_class_unregister</refname>
 <refpurpose>
     unregister a previously registered class
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>transport_class_unregister </function></funcdef>
   <paramdef>struct transport_class * <parameter>tclass</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>tclass</parameter></term>
   <listitem>
    <para>
     The transport class to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Must be called prior to deallocating the memory for the transport
   class.
</para>
</refsect1>
</refentry>

<refentry id="API-anon-transport-class-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>anon_transport_class_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>anon_transport_class_register</refname>
 <refpurpose>
     register an anonymous class
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>anon_transport_class_register </function></funcdef>
   <paramdef>struct anon_transport_class * <parameter>atc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>atc</parameter></term>
   <listitem>
    <para>
     The anon transport class to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The anonymous transport class contains both a transport class and a
   container.  The idea of an anonymous class is that it never
   actually has any device attributes associated with it (and thus
   saves on container storage).  So it can only be used for triggering
   events.  Use prezero and then use <function>DECLARE_ANON_TRANSPORT_CLASS</function> to
   initialise the anon transport class storage.
</para>
</refsect1>
</refentry>

<refentry id="API-anon-transport-class-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>anon_transport_class_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>anon_transport_class_unregister</refname>
 <refpurpose>
     unregister an anon class
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>anon_transport_class_unregister </function></funcdef>
   <paramdef>struct anon_transport_class * <parameter>atc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>atc</parameter></term>
   <listitem>
    <para>
     Pointer to the anon transport class to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Must be called prior to deallocating the memory for the anon
   transport class.
</para>
</refsect1>
</refentry>

<refentry id="API-transport-setup-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>transport_setup_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>transport_setup_device</refname>
 <refpurpose>
     declare a new dev for transport class association but don't make it visible yet.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>transport_setup_device </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the generic device representing the entity being added
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Usually, dev represents some component in the HBA system (either
   the HBA itself or a device remote across the HBA bus).  This
   routine is simply a trigger point to see if any set of transport
   classes wishes to associate with the added device.  This allocates
   storage for the class device and initialises it, but does not yet
   add it to the system or add attributes to it (you do this with
   transport_add_device).  If you have no need for a separate setup
   and add operations, use transport_register_device (see
   transport_class.h).
</para>
</refsect1>
</refentry>

<refentry id="API-transport-add-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>transport_add_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>transport_add_device</refname>
 <refpurpose>
     declare a new dev for transport class association
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>transport_add_device </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the generic device representing the entity being added
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Usually, dev represents some component in the HBA system (either
   the HBA itself or a device remote across the HBA bus).  This
   routine is simply a trigger point used to add the device to the
   system and register attributes for it.
</para>
</refsect1>
</refentry>

<refentry id="API-transport-configure-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>transport_configure_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>transport_configure_device</refname>
 <refpurpose>
     configure an already set up device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>transport_configure_device </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     generic device representing device to be configured
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The idea of configure is simply to provide a point within the setup
   process to allow the transport class to extract information from a
   device after it has been setup.  This is used in SCSI because we
   have to have a setup device to begin using the HBA, but after we
   send the initial inquiry, we use configure to extract the device
   parameters.  The device need not have been added to be configured.
</para>
</refsect1>
</refentry>

<refentry id="API-transport-remove-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>transport_remove_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>transport_remove_device</refname>
 <refpurpose>
     remove the visibility of a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>transport_remove_device </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     generic device to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call removes the visibility of the device (to the user from
   sysfs), but does not destroy it.  To eliminate a device entirely
   you must also call transport_destroy_device.  If you don't need to
   do remove and destroy as separate operations, use
   <function>transport_unregister_device</function> (see transport_class.h) which will
   perform both calls for you.
</para>
</refsect1>
</refentry>

<refentry id="API-transport-destroy-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>transport_destroy_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>transport_destroy_device</refname>
 <refpurpose>
     destroy a removed device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>transport_destroy_device </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to eliminate from the transport class.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call triggers the elimination of storage associated with the
   transport classdev.  Note: all it really does is relinquish a
   reference to the classdev.  The memory will not be freed until the
   last reference goes to zero.  Note also that the classdev retains a
   reference count on dev, so dev too will remain for as long as the
   transport class device remains around.
</para>
</refsect1>
</refentry>

<!-- Cannot be included, because
     attribute_container_add_class_device_adapter
 and attribute_container_classdev_to_container
     exceed allowed 44 characters maximum
X!Edrivers/base/attribute_container.c
-->
<!-- drivers/base/dd.c -->
<refentry id="API-device-bind-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_bind_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_bind_driver</refname>
 <refpurpose>
  bind a driver to one device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_bind_driver </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allow manual attachment of a driver to a device.
   Caller must have already set <parameter>dev</parameter>-&gt;driver.
   </para><para>

   Note that this does not modify the bus reference count
   nor take the bus's rwsem. Please verify those are accounted
   for before calling this. (It is ok to call with no other effort
   from a driver's <function>probe</function> method.)
   </para><para>

   This function must be called with the device lock held.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-for-device-probe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_for_device_probe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_for_device_probe</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>wait_for_device_probe </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Wait for device probing to be completed.
</para>
</refsect1>
</refentry>

<refentry id="API-device-attach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_attach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_attach</refname>
 <refpurpose>
     try to attach device to a driver.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_attach </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Walk the list of drivers that the bus has and call
   <function>driver_probe_device</function> for each pair. If a compatible
   pair is found, break out and return.
   </para><para>

   Returns 1 if the device was bound to a driver;
   0 if no matching driver was found;
   -ENODEV if the device is not registered.
   </para><para>

   When called for a USB interface, <parameter>dev</parameter>-&gt;parent lock must be held.
</para>
</refsect1>
</refentry>

<refentry id="API-driver-attach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>driver_attach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>driver_attach</refname>
 <refpurpose>
     try to bind driver to devices.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>driver_attach </function></funcdef>
   <paramdef><link linkend="API-struct-device-driver">struct device_driver</link> * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     driver.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Walk the list of devices that the bus has on it and try to
   match the driver with each one.  If <function>driver_probe_device</function>
   returns 0 and the <parameter>dev</parameter>-&gt;driver is set, we've found a
   compatible pair.
</para>
</refsect1>
</refentry>

<refentry id="API-device-release-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_release_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_release_driver</refname>
 <refpurpose>
     manually detach device from driver.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>device_release_driver </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Manually detach device from driver.
   When called for a USB interface, <parameter>dev</parameter>-&gt;parent lock must be held.
</para>
</refsect1>
</refentry>

<!--
X!Edrivers/base/interface.c
-->
<!-- include/linux/platform_device.h -->
<refentry id="API-platform-device-register-resndata">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_register_resndata</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_register_resndata</refname>
 <refpurpose>
  add a platform-level device with resources and platform-specific data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct platform_device * <function>platform_device_register_resndata </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>parent</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>int <parameter>id</parameter></paramdef>
   <paramdef>const struct resource * <parameter>res</parameter></paramdef>
   <paramdef>unsigned int <parameter>num</parameter></paramdef>
   <paramdef>const void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent device for the device we're adding
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     base name of the device we're adding
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     instance id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     set of resources that needs to be allocated for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num</parameter></term>
   <listitem>
    <para>
     number of resources
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     platform specific data for this platform device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of platform specific data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns <structname>struct platform_device</structname> pointer on success, or <function>ERR_PTR</function> on error.
</para>
</refsect1>
</refentry>

<refentry id="API-platform-device-register-simple">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_register_simple</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_register_simple</refname>
 <refpurpose>
     add a platform-level device and its resources
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct platform_device * <function>platform_device_register_simple </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>int <parameter>id</parameter></paramdef>
   <paramdef>const struct resource * <parameter>res</parameter></paramdef>
   <paramdef>unsigned int <parameter>num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     base name of the device we're adding
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     instance id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     set of resources that needs to be allocated for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num</parameter></term>
   <listitem>
    <para>
     number of resources
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function creates a simple platform device that requires minimal
   resource and memory management. Canned release function freeing memory
   allocated for the device allows drivers using such devices to be
   unloaded without waiting for the last reference to the device to be
   dropped.
   </para><para>

   This interface is primarily intended for use with legacy drivers which
   probe hardware directly.  Because such drivers create sysfs device nodes
   themselves, rather than letting system infrastructure handle such device
   enumeration tasks, they don't fully conform to the Linux driver model.
   In particular, when such drivers are built as modules, they can't be
   <quote>hotplugged</quote>.
   </para><para>

   Returns <structname>struct platform_device</structname> pointer on success, or <function>ERR_PTR</function> on error.
</para>
</refsect1>
</refentry>

<refentry id="API-platform-device-register-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_register_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_register_data</refname>
 <refpurpose>
     add a platform-level device with platform-specific data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct platform_device * <function>platform_device_register_data </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>parent</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>int <parameter>id</parameter></paramdef>
   <paramdef>const void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent device for the device we're adding
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     base name of the device we're adding
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     instance id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     platform specific data for this platform device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of platform specific data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function creates a simple platform device that requires minimal
   resource and memory management. Canned release function freeing memory
   allocated for the device allows drivers using such devices to be
   unloaded without waiting for the last reference to the device to be
   dropped.
   </para><para>

   Returns <structname>struct platform_device</structname> pointer on success, or <function>ERR_PTR</function> on error.
</para>
</refsect1>
</refentry>

<!-- drivers/base/platform.c -->
<refentry id="API-platform-get-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_get_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_get_resource</refname>
 <refpurpose>
  get a resource for a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct resource * <function>platform_get_resource </function></funcdef>
   <paramdef>struct platform_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>type</parameter></paramdef>
   <paramdef>unsigned int <parameter>num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     platform device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     resource type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num</parameter></term>
   <listitem>
    <para>
     resource index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-platform-get-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_get_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_get_irq</refname>
 <refpurpose>
     get an IRQ for a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>platform_get_irq </function></funcdef>
   <paramdef>struct platform_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     platform device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num</parameter></term>
   <listitem>
    <para>
     IRQ number index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-platform-get-resource-byname">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_get_resource_byname</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_get_resource_byname</refname>
 <refpurpose>
     get a resource for a device by name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct resource * <function>platform_get_resource_byname </function></funcdef>
   <paramdef>struct platform_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>type</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     platform device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     resource type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     resource name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-platform-get-irq-byname">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_get_irq_byname</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_get_irq_byname</refname>
 <refpurpose>
     get an IRQ for a device by name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>platform_get_irq_byname </function></funcdef>
   <paramdef>struct platform_device * <parameter>dev</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     platform device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     IRQ name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-platform-add-devices">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_add_devices</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_add_devices</refname>
 <refpurpose>
     add a numbers of platform devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>platform_add_devices </function></funcdef>
   <paramdef>struct platform_device ** <parameter>devs</parameter></paramdef>
   <paramdef>int <parameter>num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>devs</parameter></term>
   <listitem>
    <para>
     array of platform devices to add
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num</parameter></term>
   <listitem>
    <para>
     number of platform devices in array
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-platform-device-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_put</refname>
 <refpurpose>
     destroy a platform device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>platform_device_put </function></funcdef>
   <paramdef>struct platform_device * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     platform device to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free all memory associated with a platform device.  This function must
   _only_ be externally called in error cases.  All other usage is a bug.
</para>
</refsect1>
</refentry>

<refentry id="API-platform-device-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_alloc</refname>
 <refpurpose>
     create a platform device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct platform_device * <function>platform_device_alloc </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>int <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     base name of the device we're adding
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     instance id
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Create a platform device object which can have other objects attached
   to it, and which will have attached objects freed when it is released.
</para>
</refsect1>
</refentry>

<refentry id="API-platform-device-add-resources">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_add_resources</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_add_resources</refname>
 <refpurpose>
     add resources to a platform device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>platform_device_add_resources </function></funcdef>
   <paramdef>struct platform_device * <parameter>pdev</parameter></paramdef>
   <paramdef>const struct resource * <parameter>res</parameter></paramdef>
   <paramdef>unsigned int <parameter>num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     platform device allocated by platform_device_alloc to add resources to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     set of resources that needs to be allocated for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num</parameter></term>
   <listitem>
    <para>
     number of resources
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add a copy of the resources to the platform device.  The memory
   associated with the resources will be freed when the platform device is
   released.
</para>
</refsect1>
</refentry>

<refentry id="API-platform-device-add-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_add_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_add_data</refname>
 <refpurpose>
     add platform-specific data to a platform device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>platform_device_add_data </function></funcdef>
   <paramdef>struct platform_device * <parameter>pdev</parameter></paramdef>
   <paramdef>const void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     platform device allocated by platform_device_alloc to add resources to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     platform specific data for this platform device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of platform specific data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add a copy of platform specific data to the platform device's
   platform_data pointer.  The memory associated with the platform data
   will be freed when the platform device is released.
</para>
</refsect1>
</refentry>

<refentry id="API-platform-device-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_add</refname>
 <refpurpose>
     add a platform device to device hierarchy
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>platform_device_add </function></funcdef>
   <paramdef>struct platform_device * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     platform device we're adding
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is part 2 of <function><link linkend="API-platform-device-register">platform_device_register</link></function>, though may be called
   separately _iff_ pdev was allocated by <function><link linkend="API-platform-device-alloc">platform_device_alloc</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-platform-device-del">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_del</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_del</refname>
 <refpurpose>
     remove a platform-level device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>platform_device_del </function></funcdef>
   <paramdef>struct platform_device * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     platform device we're removing
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that this function will also release all memory- and port-based
   resources owned by the device (<parameter>dev</parameter>-&gt;resource).  This function must
   _only_ be externally called in error cases.  All other usage is a bug.
</para>
</refsect1>
</refentry>

<refentry id="API-platform-device-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_register</refname>
 <refpurpose>
     add a platform-level device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>platform_device_register </function></funcdef>
   <paramdef>struct platform_device * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     platform device we're adding
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-platform-device-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_unregister</refname>
 <refpurpose>
     unregister a platform-level device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>platform_device_unregister </function></funcdef>
   <paramdef>struct platform_device * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     platform device we're unregistering
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregistration is done in 2 steps. First we release all resources
   and remove it from the subsystem, then we drop reference count by
   calling <function><link linkend="API-platform-device-put">platform_device_put</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-platform-device-register-full">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_device_register_full</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_device_register_full</refname>
 <refpurpose>
     add a platform-level device with resources and platform-specific data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct platform_device * <function>platform_device_register_full </function></funcdef>
   <paramdef>const struct platform_device_info * <parameter>pdevinfo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdevinfo</parameter></term>
   <listitem>
    <para>
     data used to create device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns <structname>struct platform_device</structname> pointer on success, or <function>ERR_PTR</function> on error.
</para>
</refsect1>
</refentry>

<refentry id="API---platform-driver-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__platform_driver_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__platform_driver_register</refname>
 <refpurpose>
     register a driver for platform-level devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__platform_driver_register </function></funcdef>
   <paramdef>struct platform_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     platform driver structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     owning module/driver
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-platform-driver-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_driver_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_driver_unregister</refname>
 <refpurpose>
     unregister a driver for platform-level devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>platform_driver_unregister </function></funcdef>
   <paramdef>struct platform_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     platform driver structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---platform-driver-probe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__platform_driver_probe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__platform_driver_probe</refname>
 <refpurpose>
     register driver for non-hotpluggable device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__platform_driver_probe </function></funcdef>
   <paramdef>struct platform_driver * <parameter>drv</parameter></paramdef>
   <paramdef>int (*<parameter>probe</parameter>)
     <funcparams>struct platform_device *</funcparams></paramdef>
   <paramdef>struct module * <parameter>module</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     platform driver structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>probe</parameter></term>
   <listitem>
    <para>
     the driver probe routine, probably from an __init section
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>module</parameter></term>
   <listitem>
    <para>
     module which will be the owner of the driver
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use this instead of <function>platform_driver_register</function> when you know the device
   is not hotpluggable and has already been registered, and you want to
   remove its run-once <function>probe</function> infrastructure from memory after the driver
   has bound to the device.
   </para><para>

   One typical use for this would be with drivers for controllers integrated
   into system-on-chip processors, where the controller devices have been
   configured as part of board setup.
   </para><para>

   Note that this is incompatible with deferred probing.
   </para><para>

   Returns zero if the driver registered and bound to a device, else returns
   a negative error code and with the driver not registered.
</para>
</refsect1>
</refentry>

<refentry id="API---platform-create-bundle">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__platform_create_bundle</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__platform_create_bundle</refname>
 <refpurpose>
     register driver and create corresponding device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct platform_device * <function>__platform_create_bundle </function></funcdef>
   <paramdef>struct platform_driver * <parameter>driver</parameter></paramdef>
   <paramdef>int (*<parameter>probe</parameter>)
     <funcparams>struct platform_device *</funcparams></paramdef>
   <paramdef>struct resource * <parameter>res</parameter></paramdef>
   <paramdef>unsigned int <parameter>n_res</parameter></paramdef>
   <paramdef>const void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>struct module * <parameter>module</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     platform driver structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>probe</parameter></term>
   <listitem>
    <para>
     the driver probe routine, probably from an __init section
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     set of resources that needs to be allocated for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n_res</parameter></term>
   <listitem>
    <para>
     number of resources
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     platform specific data for this platform device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of platform specific data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>module</parameter></term>
   <listitem>
    <para>
     module which will be the owner of the driver
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use this in legacy-style modules that probe hardware directly and
   register a single platform device and corresponding platform driver.
   </para><para>

   Returns <structname>struct platform_device</structname> pointer on success, or <function>ERR_PTR</function> on error.
</para>
</refsect1>
</refentry>

<refentry id="API---platform-register-drivers">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__platform_register_drivers</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__platform_register_drivers</refname>
 <refpurpose>
     register an array of platform drivers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__platform_register_drivers </function></funcdef>
   <paramdef>struct platform_driver *const * <parameter>drivers</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drivers</parameter></term>
   <listitem>
    <para>
     an array of drivers to register
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of drivers to register
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     module owning the drivers
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers platform drivers specified by an array. On failure to register a
   driver, all previously registered drivers will be unregistered. Callers of
   this API should use <function><link linkend="API-platform-unregister-drivers">platform_unregister_drivers</link></function> to unregister drivers in
   the reverse order.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-platform-unregister-drivers">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_unregister_drivers</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_unregister_drivers</refname>
 <refpurpose>
     unregister an array of platform drivers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>platform_unregister_drivers </function></funcdef>
   <paramdef>struct platform_driver *const * <parameter>drivers</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drivers</parameter></term>
   <listitem>
    <para>
     an array of drivers to unregister
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of drivers to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unegisters platform drivers specified by an array. This is typically used
   to complement an earlier call to <function>platform_register_drivers</function>. Drivers are
   unregistered in the reverse order in which they were registered.
</para>
</refsect1>
</refentry>

<!-- drivers/base/bus.c -->
<refentry id="API-bus-for-each-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bus_for_each_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bus_for_each_dev</refname>
 <refpurpose>
  device iterator.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bus_for_each_dev </function></funcdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>bus</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>start</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>fn</parameter>)
     <funcparams>struct device *, void *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     bus type.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     device to start iterating from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data for the callback.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     function to be called for each device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over <parameter>bus</parameter>'s list of devices, and call <parameter>fn</parameter> for each,
   passing it <parameter>data</parameter>. If <parameter>start</parameter> is not NULL, we use that device to
   begin iterating from.
   </para><para>

   We check the return of <parameter>fn</parameter> each time. If it returns anything
   other than 0, we break out and return that value.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   The device that returns a non-zero value is not retained
   in any way, nor is its refcount incremented. If the caller needs
   to retain this data, it should do so, and increment the reference
   count in the supplied callback.
</para>
</refsect1>
</refentry>

<refentry id="API-bus-find-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bus_find_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bus_find_device</refname>
 <refpurpose>
     device iterator for locating a particular device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>bus_find_device </function></funcdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>bus</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>start</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>match</parameter>)
     <funcparams>struct device *dev, void *data</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     bus type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Device to begin with
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     Data to pass to match function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>match</parameter></term>
   <listitem>
    <para>
     Callback function to check device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is similar to the <function><link linkend="API-bus-for-each-dev">bus_for_each_dev</link></function> function above, but it
   returns a reference to a device that is 'found' for later use, as
   determined by the <parameter>match</parameter> callback.
   </para><para>

   The callback should return 0 if the device doesn't match and non-zero
   if it does.  If the callback returns non-zero, this function will
   return to the caller and not iterate over any more devices.
</para>
</refsect1>
</refentry>

<refentry id="API-bus-find-device-by-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bus_find_device_by_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bus_find_device_by_name</refname>
 <refpurpose>
     device iterator for locating a particular device of a specific name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>bus_find_device_by_name </function></funcdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>bus</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>start</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     bus type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Device to begin with
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of the device to match
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is similar to the <function><link linkend="API-bus-find-device">bus_find_device</link></function> function above, but it handles
   searching by a name automatically, no need to write another strcmp matching
   function.
</para>
</refsect1>
</refentry>

<refentry id="API-subsys-find-device-by-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>subsys_find_device_by_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>subsys_find_device_by_id</refname>
 <refpurpose>
     find a device with a specific enumeration number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>subsys_find_device_by_id </function></funcdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>subsys</parameter></paramdef>
   <paramdef>unsigned int <parameter>id</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>hint</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>subsys</parameter></term>
   <listitem>
    <para>
     subsystem
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     index 'id' in struct device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hint</parameter></term>
   <listitem>
    <para>
     device to check first
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check the hint's next object and if it is a match return it directly,
   otherwise, fall back to a full list search. Either way a reference for
   the returned object is taken.
</para>
</refsect1>
</refentry>

<refentry id="API-bus-for-each-drv">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bus_for_each_drv</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bus_for_each_drv</refname>
 <refpurpose>
     driver iterator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bus_for_each_drv </function></funcdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>bus</parameter></paramdef>
   <paramdef><link linkend="API-struct-device-driver">struct device_driver</link> * <parameter>start</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>fn</parameter>)
     <funcparams>struct device_driver *, void *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     bus we're dealing with.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     driver to start iterating on.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data to pass to the callback.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     function to call for each driver.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is nearly identical to the device iterator above.
   We iterate over each driver that belongs to <parameter>bus</parameter>, and call
   <parameter>fn</parameter> for each. If <parameter>fn</parameter> returns anything but 0, we break out
   and return it. If <parameter>start</parameter> is not NULL, we use it as the head
   of the list.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   we don't return the driver that returns a non-zero
   value, nor do we leave the reference count incremented for that
   driver. If the caller needs to know that info, it must set it
   in the callback. It must also be sure to increment the refcount
   so it doesn't disappear before returning to the caller.
</para>
</refsect1>
</refentry>

<refentry id="API-bus-rescan-devices">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bus_rescan_devices</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bus_rescan_devices</refname>
 <refpurpose>
     rescan devices on the bus for possible drivers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bus_rescan_devices </function></funcdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>bus</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     the bus to scan.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will look for devices on the bus with no driver
   attached and rescan it against existing drivers to see if it matches
   any by calling <function><link linkend="API-device-attach">device_attach</link></function> for the unbound devices.
</para>
</refsect1>
</refentry>

<refentry id="API-device-reprobe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_reprobe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_reprobe</refname>
 <refpurpose>
     remove driver for a device and probe for a new driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_reprobe </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the device to reprobe
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function detaches the attached driver (if any) for the given
   device and restarts the driver probing process.  It is intended
   to use if probing criteria changed during a devices lifetime and
   driver attachment should change accordingly.
</para>
</refsect1>
</refentry>

<refentry id="API-bus-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bus_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bus_register</refname>
 <refpurpose>
     register a driver-core subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bus_register </function></funcdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>bus</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     bus to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Once we have that, we register the bus with the kobject
   infrastructure, then register the children subsystems it has:
   the devices and drivers that belong to the subsystem.
</para>
</refsect1>
</refentry>

<refentry id="API-bus-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bus_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bus_unregister</refname>
 <refpurpose>
     remove a bus from the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>bus_unregister </function></funcdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>bus</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     bus.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregister the child subsystems and the bus itself.
   Finally, we call <function>bus_put</function> to release the refcount
</para>
</refsect1>
</refentry>

<refentry id="API-subsys-dev-iter-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>subsys_dev_iter_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>subsys_dev_iter_init</refname>
 <refpurpose>
     initialize subsys device iterator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>subsys_dev_iter_init </function></funcdef>
   <paramdef>struct subsys_dev_iter * <parameter>iter</parameter></paramdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>subsys</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>start</parameter></paramdef>
   <paramdef>const struct device_type * <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>iter</parameter></term>
   <listitem>
    <para>
     subsys iterator to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>subsys</parameter></term>
   <listitem>
    <para>
     the subsys we wanna iterate over
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     the device to start iterating from, if any
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     device_type of the devices to iterate over, NULL for all
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize subsys iterator <parameter>iter</parameter> such that it iterates over devices
   of <parameter>subsys</parameter>.  If <parameter>start</parameter> is set, the list iteration will start there,
   otherwise if it is NULL, the iteration starts at the beginning of
   the list.
</para>
</refsect1>
</refentry>

<refentry id="API-subsys-dev-iter-next">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>subsys_dev_iter_next</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>subsys_dev_iter_next</refname>
 <refpurpose>
     iterate to the next device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-device">struct device</link> * <function>subsys_dev_iter_next </function></funcdef>
   <paramdef>struct subsys_dev_iter * <parameter>iter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>iter</parameter></term>
   <listitem>
    <para>
     subsys iterator to proceed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Proceed <parameter>iter</parameter> to the next device and return it.  Returns NULL if
   iteration is complete.
   </para><para>

   The returned device is referenced and won't be released till
   iterator is proceed to the next device or exited.  The caller is
   free to do whatever it wants to do with the device including
   calling back into subsys code.
</para>
</refsect1>
</refentry>

<refentry id="API-subsys-dev-iter-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>subsys_dev_iter_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>subsys_dev_iter_exit</refname>
 <refpurpose>
     finish iteration
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>subsys_dev_iter_exit </function></funcdef>
   <paramdef>struct subsys_dev_iter * <parameter>iter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>iter</parameter></term>
   <listitem>
    <para>
     subsys iterator to finish
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finish an iteration.  Always call this function after iteration is
   complete whether the iteration ran till the end or not.
</para>
</refsect1>
</refentry>

<refentry id="API-subsys-system-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>subsys_system_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>subsys_system_register</refname>
 <refpurpose>
     register a subsystem at /sys/devices/system/
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>subsys_system_register </function></funcdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>subsys</parameter></paramdef>
   <paramdef>const struct attribute_group ** <parameter>groups</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>subsys</parameter></term>
   <listitem>
    <para>
     system subsystem
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>groups</parameter></term>
   <listitem>
    <para>
     default attributes for the root device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   All 'system' subsystems have a /sys/devices/system/&lt;name&gt; root device
   with the name of the subsystem. The root device can carry subsystem-
   wide attributes. All registered devices are below this single root
   device and are named after the subsystem with a simple enumeration
   number appended. The registered devices are not explicitly named;
   only 'id' in the device needs to be set.
   </para><para>

   Do not use this interface for anything new, it exists for compatibility
   with bad ideas only. New subsystems should use plain subsystems; and
   add the subsystem-wide attributes should be added to the subsystem
   directory itself and not some create fake root-device placed in
   /sys/devices/system/&lt;name&gt;.
</para>
</refsect1>
</refentry>

<refentry id="API-subsys-virtual-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>subsys_virtual_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>subsys_virtual_register</refname>
 <refpurpose>
     register a subsystem at /sys/devices/virtual/
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>subsys_virtual_register </function></funcdef>
   <paramdef><link linkend="API-struct-bus-type">struct bus_type</link> * <parameter>subsys</parameter></paramdef>
   <paramdef>const struct attribute_group ** <parameter>groups</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>subsys</parameter></term>
   <listitem>
    <para>
     virtual subsystem
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>groups</parameter></term>
   <listitem>
    <para>
     default attributes for the root device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   All 'virtual' subsystems have a /sys/devices/system/&lt;name&gt; root device
   with the name of the subystem.  The root device can carry subsystem-wide
   attributes.  All registered devices are below this single root device.
   There's no restriction on device naming.  This is for kernel software
   constructs which need sysfs interface.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Device Drivers DMA Management</title>
<!-- drivers/dma-buf/dma-buf.c -->
<refentry id="API-dma-buf-export">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_export</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_export</refname>
 <refpurpose>
  Creates a new dma_buf, and associates an anon file with this buffer, so it can be exported. Also connect the allocator specific data and ops to the buffer. Additionally, provide a name string for exporter; useful in debugging.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct dma_buf * <function>dma_buf_export </function></funcdef>
   <paramdef>const struct dma_buf_export_info * <parameter>exp_info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>exp_info</parameter></term>
   <listitem>
    <para>
     [in]	holds all the export related information provided
     by the exporter. see struct dma_buf_export_info
     for further details.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns, on success, a newly created dma_buf object, which wraps the
   supplied private data and operations for dma_buf_ops. On either missing
   ops, or error in allocating struct dma_buf, will return negative error.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-fd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_fd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_fd</refname>
 <refpurpose>
     returns a file descriptor for the given dma_buf
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dma_buf_fd </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	pointer to dma_buf for which fd is required.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     [in]    flags to give to fd
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   On success, returns an associated 'fd'. Else, returns error.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_get</refname>
 <refpurpose>
     returns the dma_buf structure related to an fd
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct dma_buf * <function>dma_buf_get </function></funcdef>
   <paramdef>int <parameter>fd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fd</parameter></term>
   <listitem>
    <para>
     [in]	fd associated with the dma_buf to be returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   On success, returns the dma_buf structure associated with an fd; uses
   file's refcounting done by fget to increase refcount. returns ERR_PTR
   otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_put</refname>
 <refpurpose>
     decreases refcount of the buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dma_buf_put </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer to reduce refcount of
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Uses file's refcounting done implicitly by <function>fput</function>
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-attach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_attach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_attach</refname>
 <refpurpose>
     Add the device to dma_buf's attachments list; optionally, calls <function>attach</function> of dma_buf_ops to allow device-specific attach functionality
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct dma_buf_attachment * <function>dma_buf_attach </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer to attach device to.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     [in]	device to be attached.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns struct dma_buf_attachment * for this attachment; returns ERR_PTR on
   error.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-detach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_detach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_detach</refname>
 <refpurpose>
     Remove the given attachment from dmabuf's attachments list; optionally calls <function>detach</function> of dma_buf_ops for device-specific detach
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dma_buf_detach </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
   <paramdef>struct dma_buf_attachment * <parameter>attach</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer to detach from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attach</parameter></term>
   <listitem>
    <para>
     [in]	attachment to be detached; is free'd after this call.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dma-buf-map-attachment">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_map_attachment</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_map_attachment</refname>
 <refpurpose>
     Returns the scatterlist table of the attachment; mapped into _device_ address space. Is a wrapper for <function>map_dma_buf</function> of the dma_buf_ops.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sg_table * <function>dma_buf_map_attachment </function></funcdef>
   <paramdef>struct dma_buf_attachment * <parameter>attach</parameter></paramdef>
   <paramdef>enum dma_data_direction <parameter>direction</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>attach</parameter></term>
   <listitem>
    <para>
     [in]	attachment whose scatterlist is to be returned
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>direction</parameter></term>
   <listitem>
    <para>
     [in]	direction of DMA transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns sg_table containing the scatterlist to be returned; returns ERR_PTR
   on error.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-unmap-attachment">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_unmap_attachment</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_unmap_attachment</refname>
 <refpurpose>
     unmaps and decreases usecount of the buffer;might deallocate the scatterlist associated. Is a wrapper for <function>unmap_dma_buf</function> of dma_buf_ops.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dma_buf_unmap_attachment </function></funcdef>
   <paramdef>struct dma_buf_attachment * <parameter>attach</parameter></paramdef>
   <paramdef>struct sg_table * <parameter>sg_table</parameter></paramdef>
   <paramdef>enum dma_data_direction <parameter>direction</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>attach</parameter></term>
   <listitem>
    <para>
     [in]	attachment to unmap buffer from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sg_table</parameter></term>
   <listitem>
    <para>
     [in]	scatterlist info of the buffer to unmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>direction</parameter></term>
   <listitem>
    <para>
     [in]    direction of DMA transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dma-buf-begin-cpu-access">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_begin_cpu_access</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_begin_cpu_access</refname>
 <refpurpose>
     Must be called before accessing a dma_buf from the cpu in the kernel context. Calls begin_cpu_access to allow exporter-specific preparations. Coherency is only guaranteed in the specified range for the specified access direction.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dma_buf_begin_cpu_access </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
   <paramdef>size_t <parameter>start</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
   <paramdef>enum dma_data_direction <parameter>direction</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer to prepare cpu access for.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     [in]	start of range for cpu access.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     [in]	length of range for cpu access.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>direction</parameter></term>
   <listitem>
    <para>
     [in]	length of range for cpu access.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Can return negative error values, returns 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-end-cpu-access">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_end_cpu_access</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_end_cpu_access</refname>
 <refpurpose>
     Must be called after accessing a dma_buf from the cpu in the kernel context. Calls end_cpu_access to allow exporter-specific actions. Coherency is only guaranteed in the specified range for the specified access direction.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dma_buf_end_cpu_access </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
   <paramdef>size_t <parameter>start</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
   <paramdef>enum dma_data_direction <parameter>direction</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer to complete cpu access for.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     [in]	start of range for cpu access.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     [in]	length of range for cpu access.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>direction</parameter></term>
   <listitem>
    <para>
     [in]	length of range for cpu access.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call must always succeed.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-kmap-atomic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_kmap_atomic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_kmap_atomic</refname>
 <refpurpose>
     Map a page of the buffer object into kernel address space. The same restrictions as for kmap_atomic and friends apply.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>dma_buf_kmap_atomic </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
   <paramdef>unsigned long <parameter>page_num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer to map page from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>page_num</parameter></term>
   <listitem>
    <para>
     [in]	page in PAGE_SIZE units to map.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call must always succeed, any necessary preparations that might fail
   need to be done in begin_cpu_access.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-kunmap-atomic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_kunmap_atomic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_kunmap_atomic</refname>
 <refpurpose>
     Unmap a page obtained by dma_buf_kmap_atomic.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dma_buf_kunmap_atomic </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
   <paramdef>unsigned long <parameter>page_num</parameter></paramdef>
   <paramdef>void * <parameter>vaddr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer to unmap page from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>page_num</parameter></term>
   <listitem>
    <para>
     [in]	page in PAGE_SIZE units to unmap.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vaddr</parameter></term>
   <listitem>
    <para>
     [in]	kernel space pointer obtained from dma_buf_kmap_atomic.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call must always succeed.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-kmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_kmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_kmap</refname>
 <refpurpose>
     Map a page of the buffer object into kernel address space. The same restrictions as for kmap and friends apply.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>dma_buf_kmap </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
   <paramdef>unsigned long <parameter>page_num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer to map page from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>page_num</parameter></term>
   <listitem>
    <para>
     [in]	page in PAGE_SIZE units to map.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call must always succeed, any necessary preparations that might fail
   need to be done in begin_cpu_access.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-kunmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_kunmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_kunmap</refname>
 <refpurpose>
     Unmap a page obtained by dma_buf_kmap.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dma_buf_kunmap </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
   <paramdef>unsigned long <parameter>page_num</parameter></paramdef>
   <paramdef>void * <parameter>vaddr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer to unmap page from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>page_num</parameter></term>
   <listitem>
    <para>
     [in]	page in PAGE_SIZE units to unmap.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vaddr</parameter></term>
   <listitem>
    <para>
     [in]	kernel space pointer obtained from dma_buf_kmap.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call must always succeed.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-mmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_mmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_mmap</refname>
 <refpurpose>
     Setup up a userspace mmap with the given vma
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dma_buf_mmap </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>unsigned long <parameter>pgoff</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer that should back the vma
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     [in]	vma for the mmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pgoff</parameter></term>
   <listitem>
    <para>
     [in]	offset in pages where this mmap should start within the
     dma-buf buffer.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function adjusts the passed in vma so that it points at the file of the
   dma_buf operation. It also adjusts the starting pgoff and does bounds
   checking on the size of the vma. Then it calls the exporters mmap function to
   set up the mapping.
   </para><para>

   Can return negative error values, returns 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-vmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_vmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_vmap</refname>
 <refpurpose>
     Create virtual mapping for the buffer object into kernel address space. Same restrictions as for vmap and friends apply.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>dma_buf_vmap </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer to vmap
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call may fail due to lack of virtual mapping address space.
   These calls are optional in drivers. The intended use for them
   is for mapping objects linear in kernel space for high use objects.
   Please attempt to use kmap/kunmap before thinking about these interfaces.
   </para><para>

   Returns NULL on error.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-buf-vunmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_buf_vunmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_buf_vunmap</refname>
 <refpurpose>
     Unmap a vmap obtained by dma_buf_vmap.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dma_buf_vunmap </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dmabuf</parameter></paramdef>
   <paramdef>void * <parameter>vaddr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmabuf</parameter></term>
   <listitem>
    <para>
     [in]	buffer to vunmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vaddr</parameter></term>
   <listitem>
    <para>
     [in]	vmap to vunmap
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/dma-buf/fence.c -->
<refentry id="API-fence-context-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_context_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_context_alloc</refname>
 <refpurpose>
  allocate an array of fence contexts
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned <function>fence_context_alloc </function></funcdef>
   <paramdef>unsigned <parameter>num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>num</parameter></term>
   <listitem>
    <para>
     [in]	amount of contexts to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will return the first index of the number of fences allocated.
   The fence context is used for setting fence-&gt;context to a unique number.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-signal-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_signal_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_signal_locked</refname>
 <refpurpose>
     signal completion of a fence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fence_signal_locked </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     the fence to signal
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Signal completion for software callbacks on a fence, this will unblock
   <function><link linkend="API-fence-wait">fence_wait</link></function> calls and run all the callbacks added with
   <function><link linkend="API-fence-add-callback">fence_add_callback</link></function>. Can be called multiple times, but since a fence
   can only go from unsignaled to signaled state, it will only be effective
   the first time.
   </para><para>

   Unlike fence_signal, this function must be called with fence-&gt;lock held.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-signal">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_signal</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_signal</refname>
 <refpurpose>
     signal completion of a fence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fence_signal </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     the fence to signal
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Signal completion for software callbacks on a fence, this will unblock
   <function><link linkend="API-fence-wait">fence_wait</link></function> calls and run all the callbacks added with
   <function><link linkend="API-fence-add-callback">fence_add_callback</link></function>. Can be called multiple times, but since a fence
   can only go from unsignaled to signaled state, it will only be effective
   the first time.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-wait-timeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_wait_timeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_wait_timeout</refname>
 <refpurpose>
     sleep until the fence gets signaled or until timeout elapses
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>signed long <function>fence_wait_timeout </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
   <paramdef>bool <parameter>intr</parameter></paramdef>
   <paramdef>signed long <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	the fence to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>intr</parameter></term>
   <listitem>
    <para>
     [in]	if true, do an interruptible wait
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     [in]	timeout value in jiffies, or MAX_SCHEDULE_TIMEOUT
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns -ERESTARTSYS if interrupted, 0 if the wait timed out, or the
   remaining timeout in jiffies on success. Other error values may be
   returned on custom implementations.
   </para><para>

   Performs a synchronous wait on this fence. It is assumed the caller
   directly or indirectly (buf-mgr between reservation and committing)
   holds a reference to the fence, otherwise the fence might be
   freed before return, resulting in undefined behavior.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-enable-sw-signaling">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_enable_sw_signaling</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_enable_sw_signaling</refname>
 <refpurpose>
     enable signaling on fence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fence_enable_sw_signaling </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	the fence to enable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   this will request for sw signaling to be enabled, to make the fence
   complete as soon as possible
</para>
</refsect1>
</refentry>

<refentry id="API-fence-add-callback">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_add_callback</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_add_callback</refname>
 <refpurpose>
     add a callback to be called when the fence is signaled
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fence_add_callback </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
   <paramdef><link linkend="API-struct-fence-cb">struct fence_cb</link> * <parameter>cb</parameter></paramdef>
   <paramdef>fence_func_t <parameter>func</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	the fence to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cb</parameter></term>
   <listitem>
    <para>
     [in]	the callback to register
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>func</parameter></term>
   <listitem>
    <para>
     [in]	the function to call
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   cb will be initialized by fence_add_callback, no initialization
   by the caller is required. Any number of callbacks can be registered
   to a fence, but a callback can only be registered to one fence at a time.
   </para><para>

   Note that the callback can be called from an atomic context.  If
   fence is already signaled, this function will return -ENOENT (and
   *not* call the callback)
   </para><para>

   Add a software callback to the fence. Same restrictions apply to
   refcount as it does to fence_wait, however the caller doesn't need to
</para>
</refsect1>
<refsect1>
<title>keep a refcount to fence afterwards</title>
<para>
   when software access is enabled,
   the creator of the fence is required to keep the fence alive until
   after it signals with fence_signal. The callback itself can be called
   from irq context.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-remove-callback">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_remove_callback</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_remove_callback</refname>
 <refpurpose>
     remove a callback from the signaling list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>fence_remove_callback </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
   <paramdef><link linkend="API-struct-fence-cb">struct fence_cb</link> * <parameter>cb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	the fence to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cb</parameter></term>
   <listitem>
    <para>
     [in]	the callback to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove a previously queued callback from the fence. This function returns
   true if the callback is successfully removed, or false if the fence has
   already been signaled.
   </para><para>

   *WARNING*:
   Cancelling a callback should only be done if you really know what you're
   doing, since deadlocks and race conditions could occur all too easily. For
   this reason, it should only ever be done on hardware lockup recovery,
   with a reference held to the fence.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-default-wait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_default_wait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_default_wait</refname>
 <refpurpose>
     default sleep until the fence gets signaled or until timeout elapses
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>signed long <function>fence_default_wait </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
   <paramdef>bool <parameter>intr</parameter></paramdef>
   <paramdef>signed long <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	the fence to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>intr</parameter></term>
   <listitem>
    <para>
     [in]	if true, do an interruptible wait
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     [in]	timeout value in jiffies, or MAX_SCHEDULE_TIMEOUT
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns -ERESTARTSYS if interrupted, 0 if the wait timed out, or the
   remaining timeout in jiffies on success.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-wait-any-timeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_wait_any_timeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_wait_any_timeout</refname>
 <refpurpose>
     sleep until any fence gets signaled or until timeout elapses
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>signed long <function>fence_wait_any_timeout </function></funcdef>
   <paramdef>struct fence ** <parameter>fences</parameter></paramdef>
   <paramdef>uint32_t <parameter>count</parameter></paramdef>
   <paramdef>bool <parameter>intr</parameter></paramdef>
   <paramdef>signed long <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fences</parameter></term>
   <listitem>
    <para>
     [in]	array of fences to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     [in]	number of fences to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>intr</parameter></term>
   <listitem>
    <para>
     [in]	if true, do an interruptible wait
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     [in]	timeout value in jiffies, or MAX_SCHEDULE_TIMEOUT
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns -EINVAL on custom fence wait implementation, -ERESTARTSYS if
   interrupted, 0 if the wait timed out, or the remaining timeout in jiffies
   on success.
   </para><para>

   Synchronous waits for the first fence in the array to be signaled. The
   caller needs to hold a reference to all fences in the array, otherwise a
   fence might be freed before return, resulting in undefined behavior.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_init</refname>
 <refpurpose>
     Initialize a custom fence.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fence_init </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
   <paramdef><link linkend="API-struct-fence-ops">const struct fence_ops</link> * <parameter>ops</parameter></paramdef>
   <paramdef>spinlock_t * <parameter>lock</parameter></paramdef>
   <paramdef>unsigned <parameter>context</parameter></paramdef>
   <paramdef>unsigned <parameter>seqno</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	the fence to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     [in]	the fence_ops for operations on this fence
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     [in]	the irqsafe spinlock to use for locking this fence
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>context</parameter></term>
   <listitem>
    <para>
     [in]	the execution context this fence is run on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>seqno</parameter></term>
   <listitem>
    <para>
     [in]	a linear increasing sequence number for this context
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initializes an allocated fence, the caller doesn't have to keep its
   refcount after committing with this fence, but it will need to hold a
   refcount again if fence_ops.enable_signaling gets called. This can
   be used for other implementing other types of fence.
   </para><para>

   context and seqno are used for easy comparison between fences, allowing
   to check which fence is later by simply using fence_later.
</para>
</refsect1>
</refentry>

<!-- drivers/dma-buf/seqno-fence.c -->
<refentry>
 <refnamediv>
  <refname>
   drivers/dma-buf/seqno-fence.c
  </refname>
  <refpurpose>
   Document generation inconsistency
  </refpurpose>
 </refnamediv>
 <refsect1>
  <title>
   Oops
  </title>
  <warning>
   <para>
    The template for this document tried to insert
    the structured comment from the file
    <filename>drivers/dma-buf/seqno-fence.c</filename> at this point,
    but none was found.
    This dummy section is inserted to allow
    generation to continue.
   </para>
  </warning>
 </refsect1>
</refentry>
<!-- include/linux/fence.h -->
<refentry id="API-struct-fence">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct fence</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct fence</refname>
 <refpurpose>
  software synchronization primitive
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct fence {
  struct kref refcount;
  const struct fence_ops * ops;
  struct rcu_head rcu;
  struct list_head cb_list;
  spinlock_t * lock;
  unsigned context;
  unsigned seqno;
  unsigned long flags;
  ktime_t timestamp;
  int status;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>refcount</term>
      <listitem><para>
refcount for this fence
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ops</term>
      <listitem><para>
fence_ops associated with this fence
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rcu</term>
      <listitem><para>
used for releasing fence with kfree_rcu
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cb_list</term>
      <listitem><para>
list of all callbacks to call
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
spin_lock_irqsave used for locking
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>context</term>
      <listitem><para>
execution context this fence belongs to, returned by
<function><link linkend="API-fence-context-alloc">fence_context_alloc</link></function>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>seqno</term>
      <listitem><para>
the sequence number of this fence inside the execution context,
can be compared to decide which fence would be signaled later.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
A mask of FENCE_FLAG_* defined below
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>timestamp</term>
      <listitem><para>
Timestamp when the fence was signaled.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>status</term>
      <listitem><para>
Optional, only valid if &lt; 0, must be set before calling
fence_signal, indicates that the fence has completed with an error.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   the flags member must be manipulated and read using the appropriate
   atomic ops (bit_*), so taking the spinlock will not be needed most
   of the time.
   </para><para>

   FENCE_FLAG_SIGNALED_BIT - fence is already signaled
   FENCE_FLAG_ENABLE_SIGNAL_BIT - enable_signaling might have been called*
   FENCE_FLAG_USER_BITS - start of the unused bits, can be used by the
   implementer of the fence for its own purposes. Can be used in different
   ways by different fence implementers, so do not rely on this.
   </para><para>

   *) Since atomic bitops are used, this is not guaranteed to be the case.
   Particularly, if the bit was set, but fence_signal was called right
   before this bit was set, it would have been able to set the
   FENCE_FLAG_SIGNALED_BIT, before enable_signaling was called.
   Adding a check for FENCE_FLAG_SIGNALED_BIT after setting
   FENCE_FLAG_ENABLE_SIGNAL_BIT closes this race, and makes sure that
   after fence_signal was called, any enable_signaling call will have either
   been completed, or never called at all.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-fence-cb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct fence_cb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct fence_cb</refname>
 <refpurpose>
     callback for fence_add_callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct fence_cb {
  struct list_head node;
  fence_func_t func;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>node</term>
      <listitem><para>
   used by fence_add_callback to append this struct to fence::cb_list
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>func</term>
      <listitem><para>
   fence_func_t to call
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This struct will be initialized by fence_add_callback, additional
   data can be passed along by embedding fence_cb in another struct.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-fence-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct fence_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct fence_ops</refname>
 <refpurpose>
     operations implemented for fence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct fence_ops {
  const char * (* get_driver_name) (struct fence *fence);
  const char * (* get_timeline_name) (struct fence *fence);
  bool (* enable_signaling) (struct fence *fence);
  bool (* signaled) (struct fence *fence);
  signed long (* wait) (struct fence *fence, bool intr, signed long timeout);
  void (* release) (struct fence *fence);
  int (* fill_driver_data) (struct fence *fence, void *data, int size);
  void (* fence_value_str) (struct fence *fence, char *str, int size);
  void (* timeline_value_str) (struct fence *fence, char *str, int size);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>get_driver_name</term>
      <listitem><para>
   returns the driver name.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_timeline_name</term>
      <listitem><para>
   return the name of the context this fence belongs to.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enable_signaling</term>
      <listitem><para>
   enable software signaling of fence.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>signaled</term>
      <listitem><para>
   [optional] peek whether the fence is signaled, can be null.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>wait</term>
      <listitem><para>
   custom wait implementation, or fence_default_wait.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release</term>
      <listitem><para>
   [optional] called on destruction of fence, can be null
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fill_driver_data</term>
      <listitem><para>
   [optional] callback to fill in free-form debug info
   Returns amount of bytes filled, or -errno.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fence_value_str</term>
      <listitem><para>
   [optional] fills in the value of the fence as a string
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>timeline_value_str</term>
      <listitem><para>
   [optional] fills in the current value of the timeline
   as a string
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Notes on enable_signaling</title>
<para>
   For fence implementations that have the capability for hw-&gt;hw
   signaling, they can implement this op to enable the necessary
   irqs, or insert commands into cmdstream, etc.  This is called
   in the first <function>wait</function> or <function>add_callback</function> path to let the fence
   implementation know that there is another driver waiting on
   the signal (ie. hw-&gt;sw case).
   </para><para>

   This function can be called called from atomic context, but not
   from irq context, so normal spinlocks can be used.
   </para><para>

   A return value of false indicates the fence already passed,
   or some failure occurred that made it impossible to enable
   signaling. True indicates successful enabling.
   </para><para>

   fence-&gt;status may be set in enable_signaling, but only when false is
   returned.
   </para><para>

   Calling fence_signal before enable_signaling is called allows
   for a tiny race window in which enable_signaling is called during,
   before, or after fence_signal. To fight this, it is recommended
   that before enable_signaling returns true an extra reference is
   taken on the fence, to be released when the fence is signaled.
   This will mean fence_signal will still be called twice, but
   the second time will be a noop since it was already signaled.
</para>
</refsect1>
<refsect1>
<title>Notes on signaled</title>
<para>
   May set fence-&gt;status if returning true.
</para>
</refsect1>
<refsect1>
<title>Notes on wait</title>
<para>
   Must not be NULL, set to fence_default_wait for default implementation.
   the fence_default_wait implementation should work for any fence, as long
   as enable_signaling works correctly.
   </para><para>

   Must return -ERESTARTSYS if the wait is intr = true and the wait was
   interrupted, and remaining jiffies if fence has signaled, or 0 if wait
   timed out. Can also return other error values on custom implementations,
   which should be treated as if the fence is signaled. For example a hardware
   lockup could be reported like that.
</para>
</refsect1>
<refsect1>
<title>Notes on release</title>
<para>
   Can be NULL, this function allows additional commands to run on
   destruction of the fence. Can be called from irq context.
   If pointer is set to NULL, kfree will get called instead.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_get</refname>
 <refpurpose>
     increases refcount of the fence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-fence">struct fence</link> * <function>fence_get </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	fence to increase refcount of
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the same fence, with refcount increased by 1.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-get-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_get_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_get_rcu</refname>
 <refpurpose>
     get a fence from a reservation_object_list with rcu read lock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-fence">struct fence</link> * <function>fence_get_rcu </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	fence to increase refcount of
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Function returns NULL if no refcount could be obtained, or the fence.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_put</refname>
 <refpurpose>
     decreases refcount of the fence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fence_put </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	fence to reduce refcount of
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-fence-is-signaled-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_is_signaled_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_is_signaled_locked</refname>
 <refpurpose>
     Return an indication if the fence is signaled yet.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>fence_is_signaled_locked </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	the fence to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if the fence was already signaled, false if not. Since this
   function doesn't enable signaling, it is not guaranteed to ever return
   true if fence_add_callback, fence_wait or fence_enable_sw_signaling
   haven't been called before.
   </para><para>

   This function requires fence-&gt;lock to be held.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-is-signaled">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_is_signaled</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_is_signaled</refname>
 <refpurpose>
     Return an indication if the fence is signaled yet.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>fence_is_signaled </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	the fence to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if the fence was already signaled, false if not. Since this
   function doesn't enable signaling, it is not guaranteed to ever return
   true if fence_add_callback, fence_wait or fence_enable_sw_signaling
   haven't been called before.
   </para><para>

   It's recommended for seqno fences to call fence_signal when the
   operation is complete, it makes it possible to prevent issues from
   wraparound between time of issue and time of use by checking the return
   value of this function before calling hardware-specific wait instructions.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-is-later">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_is_later</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_is_later</refname>
 <refpurpose>
     return if f1 is chronologically later than f2
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>fence_is_later </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>f1</parameter></paramdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>f2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>f1</parameter></term>
   <listitem>
    <para>
     [in]	the first fence from the same context
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>f2</parameter></term>
   <listitem>
    <para>
     [in]	the second fence from the same context
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if f1 is chronologically later than f2. Both fences must be
   from the same context, since a seqno is not re-used across contexts.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-later">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_later</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_later</refname>
 <refpurpose>
     return the chronologically later fence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-fence">struct fence</link> * <function>fence_later </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>f1</parameter></paramdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>f2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>f1</parameter></term>
   <listitem>
    <para>
     [in]	the first fence from the same context
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>f2</parameter></term>
   <listitem>
    <para>
     [in]	the second fence from the same context
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns NULL if both fences are signaled, otherwise the fence that would be
   signaled last. Both fences must be from the same context, since a seqno is
   not re-used across contexts.
</para>
</refsect1>
</refentry>

<refentry id="API-fence-wait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fence_wait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_wait</refname>
 <refpurpose>
     sleep until the fence gets signaled
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>signed long <function>fence_wait </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
   <paramdef>bool <parameter>intr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     [in]	the fence to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>intr</parameter></term>
   <listitem>
    <para>
     [in]	if true, do an interruptible wait
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will return -ERESTARTSYS if interrupted by a signal,
   or 0 if the fence was signaled. Other error values may be
   returned on custom implementations.
   </para><para>

   Performs a synchronous wait on this fence. It is assumed the caller
   directly or indirectly holds a reference to the fence, otherwise the
   fence might be freed before return, resulting in undefined behavior.
</para>
</refsect1>
</refentry>

<!-- include/linux/seqno-fence.h -->
<refentry id="API-to-seqno-fence">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>to_seqno_fence</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>to_seqno_fence</refname>
 <refpurpose>
  cast a fence to a seqno_fence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct seqno_fence * <function>to_seqno_fence </function></funcdef>
   <paramdef><link linkend="API-struct-fence">struct fence</link> * <parameter>fence</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     fence to cast to a seqno_fence
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns NULL if the fence is not a seqno_fence,
   or the seqno_fence otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-seqno-fence-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>seqno_fence_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>seqno_fence_init</refname>
 <refpurpose>
     initialize a seqno fence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>seqno_fence_init </function></funcdef>
   <paramdef>struct seqno_fence * <parameter>fence</parameter></paramdef>
   <paramdef>spinlock_t * <parameter>lock</parameter></paramdef>
   <paramdef>struct dma_buf * <parameter>sync_buf</parameter></paramdef>
   <paramdef>uint32_t <parameter>context</parameter></paramdef>
   <paramdef>uint32_t <parameter>seqno_ofs</parameter></paramdef>
   <paramdef>uint32_t <parameter>seqno</parameter></paramdef>
   <paramdef>enum seqno_fence_condition <parameter>cond</parameter></paramdef>
   <paramdef><link linkend="API-struct-fence-ops">const struct fence_ops</link> * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fence</parameter></term>
   <listitem>
    <para>
     seqno_fence to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     pointer to spinlock to use for fence
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sync_buf</parameter></term>
   <listitem>
    <para>
     buffer containing the memory location to signal on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>context</parameter></term>
   <listitem>
    <para>
     the execution context this fence is a part of
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>seqno_ofs</parameter></term>
   <listitem>
    <para>
     the offset within <parameter>sync_buf</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>seqno</parameter></term>
   <listitem>
    <para>
     the sequence # to signal on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     fence wait condition
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     the fence_ops for operations on this seqno fence
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function initializes a struct seqno_fence with passed parameters,
   and takes a reference on sync_buf which is released on fence destruction.
   </para><para>

   A seqno_fence is a dma_fence which can complete in software when
   enable_signaling is called, but it also completes when
   (s32)((sync_buf)[seqno_ofs] - seqno) &gt;= 0 is true
   </para><para>

   The seqno_fence will take a refcount on the sync_buf until it's
   destroyed, but actual lifetime of sync_buf may be longer if one of the
   callers take a reference to it.
   </para><para>

   Certain hardware have instructions to insert this type of wait condition
   in the command stream, so no intervention from software would be needed.
   This type of fence can be destroyed before completed, however a reference
   on the sync_buf dma-buf can be taken. It is encouraged to re-use the same
   dma-buf for sync_buf, since mapping or unmapping the sync_buf to the
   device's vm can be expensive.
   </para><para>

   It is recommended for creators of seqno_fence to call fence_signal
   before destruction. This will prevent possible issues from wraparound at
   time of issue vs time of check, since users can check fence_is_signaled
   before submitting instructions for the hardware to wait on the fence.
   However, when ops.enable_signaling is not called, it doesn't have to be
   done as soon as possible, just before there's any real danger of seqno
   wraparound.
</para>
</refsect1>
</refentry>

<!-- drivers/dma-buf/reservation.c -->
<refentry>
 <refnamediv>
  <refname>
   drivers/dma-buf/reservation.c
  </refname>
  <refpurpose>
   Document generation inconsistency
  </refpurpose>
 </refnamediv>
 <refsect1>
  <title>
   Oops
  </title>
  <warning>
   <para>
    The template for this document tried to insert
    the structured comment from the file
    <filename>drivers/dma-buf/reservation.c</filename> at this point,
    but none was found.
    This dummy section is inserted to allow
    generation to continue.
   </para>
  </warning>
 </refsect1>
</refentry>
<!-- include/linux/reservation.h -->
<refentry>
 <refnamediv>
  <refname>
   include/linux/reservation.h
  </refname>
  <refpurpose>
   Document generation inconsistency
  </refpurpose>
 </refnamediv>
 <refsect1>
  <title>
   Oops
  </title>
  <warning>
   <para>
    The template for this document tried to insert
    the structured comment from the file
    <filename>include/linux/reservation.h</filename> at this point,
    but none was found.
    This dummy section is inserted to allow
    generation to continue.
   </para>
  </warning>
 </refsect1>
</refentry>
<!-- drivers/base/dma-coherent.c -->
<refentry id="API-dma-alloc-from-coherent">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_alloc_from_coherent</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_alloc_from_coherent</refname>
 <refpurpose>
  try to allocate memory from the per-device coherent area
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dma_alloc_from_coherent </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>ssize_t <parameter>size</parameter></paramdef>
   <paramdef>dma_addr_t * <parameter>dma_handle</parameter></paramdef>
   <paramdef>void ** <parameter>ret</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device from which we allocate memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of requested memory area
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_handle</parameter></term>
   <listitem>
    <para>
     This will be filled with the correct dma handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ret</parameter></term>
   <listitem>
    <para>
     This pointer will be filled with the virtual address
     to allocated area.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should be only called from per-arch <function>dma_alloc_coherent</function>
   to support allocation from per-device coherent memory pools.
   </para><para>

   Returns 0 if dma_alloc_coherent should continue with allocating from
   generic memory areas, or !0 if dma_alloc_coherent should return <parameter>ret</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-release-from-coherent">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_release_from_coherent</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_release_from_coherent</refname>
 <refpurpose>
     try to free the memory allocated from per-device coherent memory pool
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dma_release_from_coherent </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>order</parameter></paramdef>
   <paramdef>void * <parameter>vaddr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device from which the memory was allocated
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>order</parameter></term>
   <listitem>
    <para>
     the order of pages allocated
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vaddr</parameter></term>
   <listitem>
    <para>
     virtual address of allocated pages
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This checks whether the memory was allocated from the per-device
   coherent memory pool and if so, releases that memory.
   </para><para>

   Returns 1 if we correctly released the memory, or 0 if
   <function>dma_release_coherent</function> should proceed with releasing memory from
   generic pools.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-mmap-from-coherent">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_mmap_from_coherent</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_mmap_from_coherent</refname>
 <refpurpose>
     try to mmap the memory allocated from per-device coherent memory pool to userspace
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dma_mmap_from_coherent </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>void * <parameter>vaddr</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>int * <parameter>ret</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device from which the memory was allocated
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     vm_area for the userspace memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vaddr</parameter></term>
   <listitem>
    <para>
     cpu address returned by dma_alloc_from_coherent
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the memory buffer allocated by dma_alloc_from_coherent
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ret</parameter></term>
   <listitem>
    <para>
     result from <function>remap_pfn_range</function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This checks whether the memory was allocated from the per-device
   coherent memory pool and if so, maps that memory to the provided vma.
   </para><para>

   Returns 1 if we correctly mapped the memory, or 0 if the caller should
   proceed with mapping memory from generic pools.
</para>
</refsect1>
</refentry>

<!-- drivers/base/dma-mapping.c -->
<refentry id="API-dmam-alloc-coherent">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmam_alloc_coherent</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmam_alloc_coherent</refname>
 <refpurpose>
  Managed <function>dma_alloc_coherent</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>dmam_alloc_coherent </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>dma_addr_t * <parameter>dma_handle</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to allocate coherent memory for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Size of allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_handle</parameter></term>
   <listitem>
    <para>
     Out argument for allocated DMA handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     Allocation flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Managed <function>dma_alloc_coherent</function>.  Memory allocated using this function
   will be automatically released on driver detach.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to allocated memory on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-dmam-free-coherent">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmam_free_coherent</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmam_free_coherent</refname>
 <refpurpose>
     Managed <function>dma_free_coherent</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dmam_free_coherent </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>void * <parameter>vaddr</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>dma_handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to free coherent memory for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Size of allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vaddr</parameter></term>
   <listitem>
    <para>
     Virtual address of the memory to free
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_handle</parameter></term>
   <listitem>
    <para>
     DMA handle of the memory to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Managed <function>dma_free_coherent</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-dmam-alloc-noncoherent">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmam_alloc_noncoherent</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmam_alloc_noncoherent</refname>
 <refpurpose>
     Managed <function>dma_alloc_non_coherent</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>dmam_alloc_noncoherent </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>dma_addr_t * <parameter>dma_handle</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to allocate non_coherent memory for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Size of allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_handle</parameter></term>
   <listitem>
    <para>
     Out argument for allocated DMA handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     Allocation flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Managed <function>dma_alloc_non_coherent</function>.  Memory allocated using this
   function will be automatically released on driver detach.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to allocated memory on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-dmam-free-noncoherent">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmam_free_noncoherent</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmam_free_noncoherent</refname>
 <refpurpose>
     Managed <function>dma_free_noncoherent</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dmam_free_noncoherent </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>void * <parameter>vaddr</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>dma_handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to free noncoherent memory for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Size of allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vaddr</parameter></term>
   <listitem>
    <para>
     Virtual address of the memory to free
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_handle</parameter></term>
   <listitem>
    <para>
     DMA handle of the memory to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Managed <function>dma_free_noncoherent</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-dmam-declare-coherent-memory">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmam_declare_coherent_memory</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmam_declare_coherent_memory</refname>
 <refpurpose>
     Managed <function>dma_declare_coherent_memory</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dmam_declare_coherent_memory </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>phys_addr_t <parameter>phys_addr</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>device_addr</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to declare coherent memory for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>phys_addr</parameter></term>
   <listitem>
    <para>
     Physical address of coherent memory to be declared
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device_addr</parameter></term>
   <listitem>
    <para>
     Device address of coherent memory to be declared
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Size of coherent memory to be declared
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     Flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Managed <function>dma_declare_coherent_memory</function>.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 on success, -errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-dmam-release-declared-memory">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmam_release_declared_memory</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmam_release_declared_memory</refname>
 <refpurpose>
     Managed <function>dma_release_declared_memory</function>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dmam_release_declared_memory </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to release declared coherent memory for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Managed <function><link linkend="API-dmam-release-declared-memory">dmam_release_declared_memory</link></function>.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Device Drivers Power Management</title>
<!-- drivers/base/power/main.c -->
<refentry id="API-dpm-resume-start">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dpm_resume_start</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dpm_resume_start</refname>
 <refpurpose>
  Execute <quote>noirq</quote> and <quote>early</quote> device callbacks.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dpm_resume_start </function></funcdef>
   <paramdef>pm_message_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     PM transition of the system being carried out.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dpm-resume-end">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dpm_resume_end</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dpm_resume_end</refname>
 <refpurpose>
     Execute <quote>resume</quote> callbacks and complete system transition.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dpm_resume_end </function></funcdef>
   <paramdef>pm_message_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     PM transition of the system being carried out.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Execute <quote>resume</quote> callbacks for all devices and complete the PM transition of
   the system.
</para>
</refsect1>
</refentry>

<refentry id="API-dpm-suspend-end">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dpm_suspend_end</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dpm_suspend_end</refname>
 <refpurpose>
     Execute <quote>late</quote> and <quote>noirq</quote> device suspend callbacks.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dpm_suspend_end </function></funcdef>
   <paramdef>pm_message_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     PM transition of the system being carried out.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dpm-suspend-start">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dpm_suspend_start</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dpm_suspend_start</refname>
 <refpurpose>
     Prepare devices for PM transition and suspend them.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dpm_suspend_start </function></funcdef>
   <paramdef>pm_message_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     PM transition of the system being carried out.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Prepare all non-sysdev devices for system PM transition and execute <quote>suspend</quote>
   callbacks for them.
</para>
</refsect1>
</refentry>

<refentry id="API-device-pm-wait-for-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_pm_wait_for_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_pm_wait_for_dev</refname>
 <refpurpose>
     Wait for suspend/resume of a device to complete.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_pm_wait_for_dev </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>subordinate</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>subordinate</parameter></term>
   <listitem>
    <para>
     Device that needs to wait for <parameter>dev</parameter>.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to wait for.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dpm-for-each-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dpm_for_each_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dpm_for_each_dev</refname>
 <refpurpose>
     device iterator.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dpm_for_each_dev </function></funcdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>void (*<parameter>fn</parameter>)
     <funcparams>struct device *, void *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data for the callback.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     function to be called for each device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over devices in dpm_list, and call <parameter>fn</parameter> for each device,
   passing it <parameter>data</parameter>.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Device Drivers ACPI Support</title>
<!-- Internal functions only
X!Edrivers/acpi/sleep/main.c
X!Edrivers/acpi/sleep/wakeup.c
X!Edrivers/acpi/motherboard.c
X!Edrivers/acpi/bus.c
-->
<!-- drivers/acpi/scan.c -->
<refentry id="API-acpi-bus-scan">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acpi_bus_scan</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acpi_bus_scan</refname>
 <refpurpose>
  Add ACPI device node objects in a given namespace scope.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>acpi_bus_scan </function></funcdef>
   <paramdef>acpi_handle <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     Root of the namespace scope to scan.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Scan a given ACPI tree (probably recently hot-plugged) and create and add
   found devices.
   </para><para>

   If no devices were found, -ENODEV is returned, but it does not mean that
   there has been a real error.  There just have been no suitable ACPI objects
   in the table trunk from which the kernel could create a device and add an
   appropriate driver.
   </para><para>

   Must be called under acpi_scan_lock.
</para>
</refsect1>
</refentry>

<refentry id="API-acpi-bus-trim">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acpi_bus_trim</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acpi_bus_trim</refname>
 <refpurpose>
     Detach scan handlers and drivers from ACPI device objects.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>acpi_bus_trim </function></funcdef>
   <paramdef>struct acpi_device * <parameter>adev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adev</parameter></term>
   <listitem>
    <para>
     Root of the ACPI namespace scope to walk.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Must be called under acpi_scan_lock.
</para>
</refsect1>
</refentry>

<!-- drivers/acpi/scan.c -->
<refentry id="API-acpi-scan-drop-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acpi_scan_drop_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acpi_scan_drop_device</refname>
 <refpurpose>
  Drop an ACPI device object.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>acpi_scan_drop_device </function></funcdef>
   <paramdef>acpi_handle <parameter>handle</parameter></paramdef>
   <paramdef>void * <parameter>context</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     Handle of an ACPI namespace node, not used.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>context</parameter></term>
   <listitem>
    <para>
     Address of the ACPI device object to drop.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is invoked by <function>acpi_ns_delete_node</function> during the removal of the ACPI
   namespace node the device object pointed to by <parameter>context</parameter> is attached to.
   </para><para>

   The unregistration is carried out asynchronously to avoid running
   <function>acpi_device_del</function> under the ACPICA's namespace mutex and the list is used to
   ensure the correct ordering (the device objects must be unregistered in the
   same order in which the corresponding namespace nodes are deleted).
</para>
</refsect1>
</refentry>

<refentry id="API-acpi-dma-supported">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acpi_dma_supported</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acpi_dma_supported</refname>
 <refpurpose>
     Check DMA support for the specified device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>acpi_dma_supported </function></funcdef>
   <paramdef>struct acpi_device * <parameter>adev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adev</parameter></term>
   <listitem>
    <para>
     The pointer to acpi device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return false if DMA is not supported. Otherwise, return true
</para>
</refsect1>
</refentry>

<refentry id="API-acpi-get-dma-attr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acpi_get_dma_attr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acpi_get_dma_attr</refname>
 <refpurpose>
     Check the supported DMA attr for the specified device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>enum dev_dma_attr <function>acpi_get_dma_attr </function></funcdef>
   <paramdef>struct acpi_device * <parameter>adev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adev</parameter></term>
   <listitem>
    <para>
     The pointer to acpi device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return enum dev_dma_attr.
</para>
</refsect1>
</refentry>

<!-- No correct structured comments
X!Edrivers/acpi/pci_bind.c
-->
     </sect1>
     <sect1><title>Device drivers PnP support</title>
<!-- drivers/pnp/core.c -->
<refentry id="API-pnp-register-protocol">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_register_protocol</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_register_protocol</refname>
 <refpurpose>
  adds a pnp protocol to the pnp layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pnp_register_protocol </function></funcdef>
   <paramdef>struct pnp_protocol * <parameter>protocol</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>protocol</parameter></term>
   <listitem>
    <para>
     pointer to the corresponding pnp_protocol structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Ex protocols</title>
<para>
   ISAPNP, PNPBIOS, etc
</para>
</refsect1>
</refentry>

<refentry id="API-pnp-unregister-protocol">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_unregister_protocol</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_unregister_protocol</refname>
 <refpurpose>
     removes a pnp protocol from the pnp layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pnp_unregister_protocol </function></funcdef>
   <paramdef>struct pnp_protocol * <parameter>protocol</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>protocol</parameter></term>
   <listitem>
    <para>
     pointer to the corresponding pnp_protocol structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- No correct structured comments
X!Edrivers/pnp/system.c
 -->
<!-- drivers/pnp/card.c -->
<refentry id="API-pnp-request-card-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_request_card_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_request_card_device</refname>
 <refpurpose>
  Searches for a PnP device under the specified card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pnp_dev * <function>pnp_request_card_device </function></funcdef>
   <paramdef>struct pnp_card_link * <parameter>clink</parameter></paramdef>
   <paramdef>const char * <parameter>id</parameter></paramdef>
   <paramdef>struct pnp_dev * <parameter>from</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clink</parameter></term>
   <listitem>
    <para>
     pointer to the card link, cannot be NULL
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     pointer to a PnP ID structure that explains the rules for finding the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     Starting place to search from. If NULL it will start from the beginning.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pnp-release-card-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_release_card_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_release_card_device</refname>
 <refpurpose>
     call this when the driver no longer needs the device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pnp_release_card_device </function></funcdef>
   <paramdef>struct pnp_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the PnP device structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pnp-register-card-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_register_card_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_register_card_driver</refname>
 <refpurpose>
     registers a PnP card driver with the PnP Layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pnp_register_card_driver </function></funcdef>
   <paramdef>struct pnp_card_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     pointer to the driver to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pnp-unregister-card-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_unregister_card_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_unregister_card_driver</refname>
 <refpurpose>
     unregisters a PnP card driver from the PnP Layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pnp_unregister_card_driver </function></funcdef>
   <paramdef>struct pnp_card_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     pointer to the driver to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/pnp/driver.c -->
<refentry id="API-pnp-add-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_add_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_add_id</refname>
 <refpurpose>
  adds an EISA id to the specified device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pnp_id * <function>pnp_add_id </function></funcdef>
   <paramdef>struct pnp_dev * <parameter>dev</parameter></paramdef>
   <paramdef>const char * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the desired device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     pointer to an EISA id string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/pnp/manager.c -->
<refentry id="API-pnp-start-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_start_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_start_dev</refname>
 <refpurpose>
  low-level start of the PnP device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pnp_start_dev </function></funcdef>
   <paramdef>struct pnp_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the desired device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   assumes that resources have already been allocated
</para>
</refsect1>
</refentry>

<refentry id="API-pnp-stop-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_stop_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_stop_dev</refname>
 <refpurpose>
     low-level disable of the PnP device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pnp_stop_dev </function></funcdef>
   <paramdef>struct pnp_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the desired device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   does not free resources
</para>
</refsect1>
</refentry>

<refentry id="API-pnp-activate-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_activate_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_activate_dev</refname>
 <refpurpose>
     activates a PnP device for use
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pnp_activate_dev </function></funcdef>
   <paramdef>struct pnp_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the desired device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   does not validate or set resources so be careful.
</para>
</refsect1>
</refentry>

<refentry id="API-pnp-disable-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_disable_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_disable_dev</refname>
 <refpurpose>
     disables device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pnp_disable_dev </function></funcdef>
   <paramdef>struct pnp_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the desired device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   inform the correct pnp protocol so that resources can be used by other devices
</para>
</refsect1>
</refentry>

<!-- drivers/pnp/support.c -->
<refentry id="API-pnp-is-active">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_is_active</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_is_active</refname>
 <refpurpose>
  Determines if a device is active based on its current resources
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pnp_is_active </function></funcdef>
   <paramdef>struct pnp_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the desired PnP device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Userspace IO devices</title>
<!-- drivers/uio/uio.c -->
<refentry id="API-uio-event-notify">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uio_event_notify</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uio_event_notify</refname>
 <refpurpose>
  trigger an interrupt event
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uio_event_notify </function></funcdef>
   <paramdef><link linkend="API-struct-uio-info">struct uio_info</link> * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     UIO device capabilities
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---uio-register-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__uio_register_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__uio_register_device</refname>
 <refpurpose>
     register a new userspace IO device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__uio_register_device </function></funcdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>parent</parameter></paramdef>
   <paramdef><link linkend="API-struct-uio-info">struct uio_info</link> * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     module that creates the new device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     UIO device capabilities
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   returns zero on success or a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-uio-unregister-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uio_unregister_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uio_unregister_device</refname>
 <refpurpose>
     unregister a industrial IO device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uio_unregister_device </function></funcdef>
   <paramdef><link linkend="API-struct-uio-info">struct uio_info</link> * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     UIO device capabilities
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- include/linux/uio_driver.h -->
<refentry id="API-struct-uio-mem">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct uio_mem</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct uio_mem</refname>
 <refpurpose>
  description of a UIO memory region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct uio_mem {
  const char * name;
  phys_addr_t addr;
  resource_size_t size;
  int memtype;
  void __iomem * internal_addr;
  struct uio_map * map;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name</term>
      <listitem><para>
name of the memory region for identification
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>addr</term>
      <listitem><para>
address of the device's memory (phys_addr is used since
addr can be logical, virtual, or physical &amp; phys_addr_t
should always be large enough to handle any of the
address types)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>size</term>
      <listitem><para>
size of IO
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>memtype</term>
      <listitem><para>
type of memory addr points to
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>internal_addr</term>
      <listitem><para>
ioremap-ped version of addr, for driver internal use
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>map</term>
      <listitem><para>
for use by the UIO core only.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-uio-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct uio_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct uio_port</refname>
 <refpurpose>
     description of a UIO port region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct uio_port {
  const char * name;
  unsigned long start;
  unsigned long size;
  int porttype;
  struct uio_portio * portio;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name</term>
      <listitem><para>
   name of the port region for identification
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start</term>
      <listitem><para>
   start of port region
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>size</term>
      <listitem><para>
   size of port region
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>porttype</term>
      <listitem><para>
   type of port (see UIO_PORT_* below)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>portio</term>
      <listitem><para>
   for use by the UIO core only.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-uio-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct uio_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct uio_info</refname>
 <refpurpose>
     UIO device capabilities
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct uio_info {
  struct uio_device * uio_dev;
  const char * name;
  const char * version;
  struct uio_mem mem[MAX_UIO_MAPS];
  struct uio_port port[MAX_UIO_PORT_REGIONS];
  long irq;
  unsigned long irq_flags;
  void * priv;
  irqreturn_t (* handler) (int irq, struct uio_info *dev_info);
  int (* mmap) (struct uio_info *info, struct vm_area_struct *vma);
  int (* open) (struct uio_info *info, struct inode *inode);
  int (* release) (struct uio_info *info, struct inode *inode);
  int (* irqcontrol) (struct uio_info *info, s32 irq_on);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>uio_dev</term>
      <listitem><para>
   the UIO device this info belongs to
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name</term>
      <listitem><para>
   device name
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>version</term>
      <listitem><para>
   device driver version
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mem[MAX_UIO_MAPS]</term>
      <listitem><para>
   list of mappable memory regions, size==0 for end of list
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port[MAX_UIO_PORT_REGIONS]</term>
      <listitem><para>
   list of port regions, size==0 for end of list
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>irq</term>
      <listitem><para>
   interrupt number or UIO_IRQ_CUSTOM
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>irq_flags</term>
      <listitem><para>
   flags for <function>request_irq</function>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>priv</term>
      <listitem><para>
   optional private data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>handler</term>
      <listitem><para>
   the device's irq handler
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mmap</term>
      <listitem><para>
   mmap operation for this uio device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>open</term>
      <listitem><para>
   open operation for this uio device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release</term>
      <listitem><para>
   release operation for this uio device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>irqcontrol</term>
      <listitem><para>
   disable/enable irqs when 0/1 is written to /dev/uioX
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="parportdev">
     <title>Parallel Port Devices</title>
<!-- include/linux/parport.h -->
<refentry id="API-parport-yield">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_yield</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_yield</refname>
 <refpurpose>
  relinquish a parallel port temporarily
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_yield </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     a device on the parallel port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function relinquishes the port if it would be helpful to other
   drivers to do so.  Afterwards it tries to reclaim the port using
   <function><link linkend="API-parport-claim">parport_claim</link></function>, and the return value is the same as for
   <function><link linkend="API-parport-claim">parport_claim</link></function>.  If it fails, the port is left unclaimed and it is
   the driver's responsibility to reclaim the port.
   </para><para>

   The <function><link linkend="API-parport-yield">parport_yield</link></function> and <function><link linkend="API-parport-yield-blocking">parport_yield_blocking</link></function> functions are for
   marking points in the driver at which other drivers may claim the
   port and use their devices.  Yielding the port is similar to
   releasing it and reclaiming it, but is more efficient because no
   action is taken if there are no other devices needing the port.  In
   fact, nothing is done even if there are other devices waiting but
   the current device is still within its <quote>timeslice</quote>.  The default
   timeslice is half a second, but it can be adjusted via the /proc
   interface.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-yield-blocking">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_yield_blocking</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_yield_blocking</refname>
 <refpurpose>
     relinquish a parallel port temporarily
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_yield_blocking </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     a device on the parallel port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function relinquishes the port if it would be helpful to other
   drivers to do so.  Afterwards it tries to reclaim the port using
   <function><link linkend="API-parport-claim-or-block">parport_claim_or_block</link></function>, and the return value is the same as for
   <function><link linkend="API-parport-claim-or-block">parport_claim_or_block</link></function>.
</para>
</refsect1>
</refentry>

<!-- drivers/parport/ieee1284.c -->
<refentry id="API-parport-wait-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_wait_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_wait_event</refname>
 <refpurpose>
  wait for an event on a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_wait_event </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
   <paramdef>signed long <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     port to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     time to wait (in jiffies)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function waits for up to <parameter>timeout</parameter> jiffies for an
   interrupt to occur on a parallel port.  If the port timeout is
   set to zero, it returns immediately.
   </para><para>

   If an interrupt occurs before the timeout period elapses, this
   function returns zero immediately.  If it times out, it returns
   one.  An error code less than zero indicates an error (most
   likely a pending signal), and the calling code should finish
   what it's doing as soon as it can.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-wait-peripheral">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_wait_peripheral</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_wait_peripheral</refname>
 <refpurpose>
     wait for status lines to change in 35ms
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_wait_peripheral </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
   <paramdef>unsigned char <parameter>mask</parameter></paramdef>
   <paramdef>unsigned char <parameter>result</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     port to watch
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     status lines to watch
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>result</parameter></term>
   <listitem>
    <para>
     desired values of chosen status lines
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function waits until the masked status lines have the
   desired values, or until 35ms have elapsed (see IEEE 1284-1994
   page 24 to 25 for why this value in particular is hardcoded).
   The <parameter>mask</parameter> and <parameter>result</parameter> parameters are bitmasks, with the bits
   defined by the constants in parport.h: <constant>PARPORT_STATUS_BUSY</constant>,
   and so on.
   </para><para>

   The port is polled quickly to start off with, in anticipation
   of a fast response from the peripheral.  This fast polling
   time is configurable (using /proc), and defaults to 500usec.
   If the timeout for this port (see <function><link linkend="API-parport-set-timeout">parport_set_timeout</link></function>) is
   zero, the fast polling time is 35ms, and this function does
   not call <function>schedule</function>.
   </para><para>

   If the timeout for this port is non-zero, after the fast
   polling fails it uses <function><link linkend="API-parport-wait-event">parport_wait_event</link></function> to wait for up to
   10ms, waking up if an interrupt occurs.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-negotiate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_negotiate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_negotiate</refname>
 <refpurpose>
     negotiate an IEEE 1284 mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_negotiate </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
   <paramdef>int <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     port to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode to negotiate to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use this to negotiate to a particular IEEE 1284 transfer mode.
   The <parameter>mode</parameter> parameter should be one of the constants in
   parport.h starting <constant>IEEE1284_MODE_xxx</constant>.
   </para><para>

   The return value is 0 if the peripheral has accepted the
   negotiation to the mode specified, -1 if the peripheral is not
   IEEE 1284 compliant (or not present), or 1 if the peripheral
   has rejected the negotiation.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_write</refname>
 <refpurpose>
     write a block of data to a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>parport_write </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
   <paramdef>const void * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     port to write to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     data buffer (in kernel space)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes of data to transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This will write up to <parameter>len</parameter> bytes of <parameter>buffer</parameter> to the port
   specified, using the IEEE 1284 transfer mode most recently
   negotiated to (using <function><link linkend="API-parport-negotiate">parport_negotiate</link></function>), as long as that
   mode supports forward transfers (host to peripheral).
   </para><para>

   It is the caller's responsibility to ensure that the first
   <parameter>len</parameter> bytes of <parameter>buffer</parameter> are valid.
   </para><para>

   This function returns the number of bytes transferred (if zero
   or positive), or else an error code.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_read</refname>
 <refpurpose>
     read a block of data from a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>parport_read </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
   <paramdef>void * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     port to read from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     data buffer (in kernel space)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes of data to transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This will read up to <parameter>len</parameter> bytes of <parameter>buffer</parameter> to the port
   specified, using the IEEE 1284 transfer mode most recently
   negotiated to (using <function><link linkend="API-parport-negotiate">parport_negotiate</link></function>), as long as that
   mode supports reverse transfers (peripheral to host).
   </para><para>

   It is the caller's responsibility to ensure that the first
   <parameter>len</parameter> bytes of <parameter>buffer</parameter> are available to write to.
   </para><para>

   This function returns the number of bytes transferred (if zero
   or positive), or else an error code.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-set-timeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_set_timeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_set_timeout</refname>
 <refpurpose>
     set the inactivity timeout for a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>parport_set_timeout </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
   <paramdef>long <parameter>inactivity</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device on a port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>inactivity</parameter></term>
   <listitem>
    <para>
     inactivity timeout (in jiffies)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This sets the inactivity timeout for a particular device on a
   port.  This affects functions like <function><link linkend="API-parport-wait-peripheral">parport_wait_peripheral</link></function>.
   The special value 0 means not to call <function>schedule</function> while dealing
   with this device.
   </para><para>

   The return value is the previous inactivity timeout.
   </para><para>

   Any callers of <function><link linkend="API-parport-wait-event">parport_wait_event</link></function> for this device are woken
   up.
</para>
</refsect1>
</refentry>

<!-- drivers/parport/share.c -->
<refentry id="API---parport-register-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__parport_register_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__parport_register_driver</refname>
 <refpurpose>
  register a parallel port device driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__parport_register_driver </function></funcdef>
   <paramdef>struct parport_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
   <paramdef>const char * <parameter>mod_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     structure describing the driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     owner module of drv
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mod_name</parameter></term>
   <listitem>
    <para>
     module name string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This can be called by a parallel port device driver in order
   to receive notifications about ports being found in the
   system, as well as ports no longer available.
   </para><para>

   If devmodel is true then the new device model is used
   for registration.
   </para><para>

   The <parameter>drv</parameter> structure is allocated by the caller and must not be
   deallocated until after calling <function><link linkend="API-parport-unregister-driver">parport_unregister_driver</link></function>.
</para>
</refsect1>
<refsect1>
<title>If using the non device model</title>
<para>
   The driver's <function>attach</function> function may block.  The port that
   <function>attach</function> is given will be valid for the duration of the
   callback, but if the driver wants to take a copy of the
   pointer it must call <function><link linkend="API-parport-get-port">parport_get_port</link></function> to do so.  Calling
   <function><link linkend="API-parport-register-device">parport_register_device</link></function> on that port will do this for you.
   </para><para>

   The driver's <function>detach</function> function may block.  The port that
   <function>detach</function> is given will be valid for the duration of the
   callback, but if the driver wants to take a copy of the
   pointer it must call <function><link linkend="API-parport-get-port">parport_get_port</link></function> to do so.
   </para><para>

   </para><para>

   Returns 0 on success. The non device model will always succeeds.
   but the new device model can fail and will return the error code.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-unregister-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_unregister_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_unregister_driver</refname>
 <refpurpose>
     deregister a parallel port device driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_unregister_driver </function></funcdef>
   <paramdef>struct parport_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     structure describing the driver that was given to
     <function>parport_register_driver</function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This should be called by a parallel port device driver that
   has registered itself using <function>parport_register_driver</function> when it
   is about to be unloaded.
   </para><para>

   When it returns, the driver's <function>attach</function> routine will no longer
   be called, and for each port that <function>attach</function> was called for, the
   <function>detach</function> routine will have been called.
   </para><para>

   All the driver's <function>attach</function> and <function>detach</function> calls are guaranteed to have
   finished by the time this function returns.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-get-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_get_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_get_port</refname>
 <refpurpose>
     increment a port's reference count
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct parport * <function>parport_get_port </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     the port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This ensures that a struct parport pointer remains valid
   until the matching <function><link linkend="API-parport-put-port">parport_put_port</link></function> call.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-put-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_put_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_put_port</refname>
 <refpurpose>
     decrement a port's reference count
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_put_port </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     the port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This should be called once for each call to <function><link linkend="API-parport-get-port">parport_get_port</link></function>,
   once the port is no longer needed. When the reference count reaches
   zero (port is no longer used), free_port is called.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-register-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_register_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_register_port</refname>
 <refpurpose>
     register a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct parport * <function>parport_register_port </function></funcdef>
   <paramdef>unsigned long <parameter>base</parameter></paramdef>
   <paramdef>int <parameter>irq</parameter></paramdef>
   <paramdef>int <parameter>dma</parameter></paramdef>
   <paramdef>struct parport_operations * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     base I/O address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     IRQ line
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma</parameter></term>
   <listitem>
    <para>
     DMA channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     pointer to the port driver's port operations structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When a parallel port (lowlevel) driver finds a port that
   should be made available to parallel port device drivers, it
   should call <function><link linkend="API-parport-register-port">parport_register_port</link></function>.  The <parameter>base</parameter>, <parameter>irq</parameter>, and
   <parameter>dma</parameter> parameters are for the convenience of port drivers, and
   for ports where they aren't meaningful needn't be set to
   anything special.  They can be altered afterwards by adjusting
   the relevant members of the parport structure that is returned
   and represents the port.  They should not be tampered with
   after calling parport_announce_port, however.
   </para><para>

   If there are parallel port device drivers in the system that
   have registered themselves using <function>parport_register_driver</function>,
   they are not told about the port at this time; that is done by
   <function><link linkend="API-parport-announce-port">parport_announce_port</link></function>.
   </para><para>

   The <parameter>ops</parameter> structure is allocated by the caller, and must not be
   deallocated before calling <function><link linkend="API-parport-remove-port">parport_remove_port</link></function>.
   </para><para>

   If there is no memory to allocate a new parport structure,
   this function will return <constant>NULL</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-announce-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_announce_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_announce_port</refname>
 <refpurpose>
     tell device drivers about a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_announce_port </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     parallel port to announce
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   After a port driver has registered a parallel port with
   parport_register_port, and performed any necessary
   initialisation or adjustments, it should call
   <function><link linkend="API-parport-announce-port">parport_announce_port</link></function> in order to notify all device drivers
   that have called <function>parport_register_driver</function>.  Their <function>attach</function>
   functions will be called, with <parameter>port</parameter> as the parameter.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-remove-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_remove_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_remove_port</refname>
 <refpurpose>
     deregister a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_remove_port </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     parallel port to deregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When a parallel port driver is forcibly unloaded, or a
   parallel port becomes inaccessible, the port driver must call
   this function in order to deal with device drivers that still
   want to use it.
   </para><para>

   The parport structure associated with the port has its
   operations structure replaced with one containing 'null'
   operations that return errors or just don't do anything.
   </para><para>

   Any drivers that have registered themselves using
   <function>parport_register_driver</function> are notified that the port is no
   longer accessible by having their <function>detach</function> routines called
   with <parameter>port</parameter> as the parameter.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-register-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_register_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_register_device</refname>
 <refpurpose>
     register a device on a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pardevice * <function>parport_register_device </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>int (*<parameter>pf</parameter>)
     <funcparams>void *</funcparams></paramdef>
   <paramdef>void (*<parameter>kf</parameter>)
     <funcparams>void *</funcparams></paramdef>
   <paramdef>void (*<parameter>irq_func</parameter>)
     <funcparams>void *</funcparams></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
   <paramdef>void * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     port to which the device is attached
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     a name to refer to the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pf</parameter></term>
   <listitem>
    <para>
     preemption callback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kf</parameter></term>
   <listitem>
    <para>
     kick callback (wake-up)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>irq_func</parameter></term>
   <listitem>
    <para>
     interrupt handler
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     registration flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     data for callback functions
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function, called by parallel port device drivers,
   declares that a device is connected to a port, and tells the
   system all it needs to know.
   </para><para>

   The <parameter>name</parameter> is allocated by the caller and must not be
   deallocated until the caller calls <parameter>parport_unregister_device</parameter>
   for that device.
   </para><para>

   The preemption callback function, <parameter>pf</parameter>, is called when this
   device driver has claimed access to the port but another
   device driver wants to use it.  It is given <parameter>handle</parameter> as its
   parameter, and should return zero if it is willing for the
   system to release the port to another driver on its behalf.
   If it wants to keep control of the port it should return
   non-zero, and no action will be taken.  It is good manners for
   the driver to try to release the port at the earliest
   opportunity after its preemption callback rejects a preemption
   attempt.  Note that if a preemption callback is happy for
   preemption to go ahead, there is no need to release the port;
   it is done automatically.  This function may not block, as it
   may be called from interrupt context.  If the device driver
   does not support preemption, <parameter>pf</parameter> can be <constant>NULL</constant>.
   </para><para>

   The wake-up (<quote>kick</quote>) callback function, <parameter>kf</parameter>, is called when
   the port is available to be claimed for exclusive access; that
   is, <function><link linkend="API-parport-claim">parport_claim</link></function> is guaranteed to succeed when called from
   inside the wake-up callback function.  If the driver wants to
   claim the port it should do so; otherwise, it need not take
   any action.  This function may not block, as it may be called
   from interrupt context.  If the device driver does not want to
   be explicitly invited to claim the port in this way, <parameter>kf</parameter> can
   be <constant>NULL</constant>.
   </para><para>

   The interrupt handler, <parameter>irq_func</parameter>, is called when an interrupt
   arrives from the parallel port.  Note that if a device driver
   wants to use interrupts it should use <function>parport_enable_irq</function>,
   and can also check the irq member of the parport structure
   representing the port.
   </para><para>

   The parallel port (lowlevel) driver is the one that has called
   <function>request_irq</function> and whose interrupt handler is called first.
   This handler does whatever needs to be done to the hardware to
   acknowledge the interrupt (for PC-style ports there is nothing
   special to be done).  It then tells the IEEE 1284 code about
   the interrupt, which may involve reacting to an IEEE 1284
   event depending on the current IEEE 1284 phase.  After this,
   it calls <parameter>irq_func</parameter>.  Needless to say, <parameter>irq_func</parameter> will be called
   from interrupt context, and may not block.
   </para><para>

   The <constant>PARPORT_DEV_EXCL</constant> flag is for preventing port sharing, and
   so should only be used when sharing the port with other device
   drivers is impossible and would lead to incorrect behaviour.
   Use it sparingly!  Normally, <parameter>flags</parameter> will be zero.
   </para><para>

   This function returns a pointer to a structure that represents
   the device on the port, or <constant>NULL</constant> if there is not enough memory
   to allocate space for that structure.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-unregister-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_unregister_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_unregister_device</refname>
 <refpurpose>
     deregister a device on a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_unregister_device </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to structure representing device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This undoes the effect of <function><link linkend="API-parport-register-device">parport_register_device</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-find-number">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_find_number</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_find_number</refname>
 <refpurpose>
     find a parallel port by number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct parport * <function>parport_find_number </function></funcdef>
   <paramdef>int <parameter>number</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>number</parameter></term>
   <listitem>
    <para>
     parallel port number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns the parallel port with the specified number, or
   <constant>NULL</constant> if there is none.
   </para><para>

   There is an implicit <function><link linkend="API-parport-get-port">parport_get_port</link></function> done already; to throw
   away the reference to the port that <function><link linkend="API-parport-find-number">parport_find_number</link></function>
   gives you, use <function><link linkend="API-parport-put-port">parport_put_port</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-find-base">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_find_base</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_find_base</refname>
 <refpurpose>
     find a parallel port by base address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct parport * <function>parport_find_base </function></funcdef>
   <paramdef>unsigned long <parameter>base</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     base I/O address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns the parallel port with the specified base
   address, or <constant>NULL</constant> if there is none.
   </para><para>

   There is an implicit <function><link linkend="API-parport-get-port">parport_get_port</link></function> done already; to throw
   away the reference to the port that <function><link linkend="API-parport-find-base">parport_find_base</link></function>
   gives you, use <function><link linkend="API-parport-put-port">parport_put_port</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-claim">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_claim</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_claim</refname>
 <refpurpose>
     claim access to a parallel port device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_claim </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to structure representing a device on the port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will not block and so can be used from interrupt
   context.  If <function><link linkend="API-parport-claim">parport_claim</link></function> succeeds in claiming access to
   the port it returns zero and the port is available to use.  It
   may fail (returning non-zero) if the port is in use by another
   driver and that driver is not willing to relinquish control of
   the port.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-claim-or-block">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_claim_or_block</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_claim_or_block</refname>
 <refpurpose>
     claim access to a parallel port device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_claim_or_block </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to structure representing a device on the port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This behaves like <function><link linkend="API-parport-claim">parport_claim</link></function>, but will block if necessary
   to wait for the port to be free.  A return value of 1
   indicates that it slept; 0 means that it succeeded without
   needing to sleep.  A negative error code indicates failure.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_release</refname>
 <refpurpose>
     give up access to a parallel port device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_release </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to structure representing parallel port device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function cannot fail, but it should not be called without
   the port claimed.  Similarly, if the port is already claimed
   you should not try claiming it again.
</para>
</refsect1>
</refentry>

<!-- drivers/parport/daisy.c -->
<refentry id="API-parport-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_open</refname>
 <refpurpose>
  find a device by canonical device number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pardevice * <function>parport_open </function></funcdef>
   <paramdef>int <parameter>devnum</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>devnum</parameter></term>
   <listitem>
    <para>
     canonical device number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name to associate with the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is similar to <function><link linkend="API-parport-register-device">parport_register_device</link></function>, except
   that it locates a device by its number rather than by the port
   it is attached to.
   </para><para>

   All parameters except for <parameter>devnum</parameter> are the same as for
   <function><link linkend="API-parport-register-device">parport_register_device</link></function>.  The return value is the same as
   for <function><link linkend="API-parport-register-device">parport_register_device</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-close">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_close</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_close</refname>
 <refpurpose>
     close a device opened with <function><link linkend="API-parport-open">parport_open</link></function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_close </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to close
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is to <function><link linkend="API-parport-open">parport_open</link></function> as <function><link linkend="API-parport-unregister-device">parport_unregister_device</link></function> is to
   <function><link linkend="API-parport-register-device">parport_register_device</link></function>.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="message_devices">
	<title>Message-based devices</title>
     <sect1><title>Fusion message devices</title>
<!-- drivers/message/fusion/mptbase.c -->
<refentry id="API-mpt-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_register</refname>
 <refpurpose>
  Register protocol-specific main callback handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u8 <function>mpt_register </function></funcdef>
   <paramdef>MPT_CALLBACK <parameter>cbfunc</parameter></paramdef>
   <paramdef>MPT_DRIVER_CLASS <parameter>dclass</parameter></paramdef>
   <paramdef>char * <parameter>func_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cbfunc</parameter></term>
   <listitem>
    <para>
     callback function pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dclass</parameter></term>
   <listitem>
    <para>
     Protocol driver's class (<constant>MPT_DRIVER_CLASS</constant> enum value)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>func_name</parameter></term>
   <listitem>
    <para>
     call function's name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is called by a protocol-specific driver (SCSI host,
   LAN, SCSI target) to register its reply callback routine.  Each
   protocol-specific driver must do this before it will be able to
   use any IOC resources, such as obtaining request frames.
</para>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   The SCSI protocol driver currently calls this routine thrice
   in order to register separate callbacks; one for <quote>normal</quote> SCSI IO;
   one for MptScsiTaskMgmt requests; one for Scan/DV requests.
   </para><para>

   Returns u8 valued <quote>handle</quote> in the range (and S.O.D. order)
   {N,...,7,6,5,...,1} if successful.
   A return value of MPT_MAX_PROTOCOL_DRIVERS (including zero!) should be
   considered an error by the caller.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-deregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_deregister</refname>
 <refpurpose>
     Deregister a protocol drivers resources.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_deregister </function></funcdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     previously registered callback handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each protocol-specific driver should call this routine when its
   module is unloaded.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-event-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_event_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_event_register</refname>
 <refpurpose>
     Register protocol-specific event callback handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_event_register </function></funcdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
   <paramdef>MPT_EVHANDLER <parameter>ev_cbfunc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     previously registered (via mpt_register) callback handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ev_cbfunc</parameter></term>
   <listitem>
    <para>
     callback function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine can be called by one or more protocol-specific drivers
   if/when they choose to be notified of MPT events.
   </para><para>

   Returns 0 for success.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-event-deregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_event_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_event_deregister</refname>
 <refpurpose>
     Deregister protocol-specific event callback handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_event_deregister </function></funcdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     previously registered callback handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each protocol-specific driver should call this routine
   when it does not (or can no longer) handle events,
   or when its module is unloaded.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-reset-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_reset_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_reset_register</refname>
 <refpurpose>
     Register protocol-specific IOC reset handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_reset_register </function></funcdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
   <paramdef>MPT_RESETHANDLER <parameter>reset_func</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     previously registered (via mpt_register) callback handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reset_func</parameter></term>
   <listitem>
    <para>
     reset function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine can be called by one or more protocol-specific drivers
   if/when they choose to be notified of IOC resets.
   </para><para>

   Returns 0 for success.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-reset-deregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_reset_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_reset_deregister</refname>
 <refpurpose>
     Deregister protocol-specific IOC reset handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_reset_deregister </function></funcdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     previously registered callback handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each protocol-specific driver should call this routine
   when it does not (or can no longer) handle IOC reset handling,
   or when its module is unloaded.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-device-driver-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_device_driver_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_device_driver_register</refname>
 <refpurpose>
     Register device driver hooks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_device_driver_register </function></funcdef>
   <paramdef>struct mpt_pci_driver * <parameter>dd_cbfunc</parameter></paramdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dd_cbfunc</parameter></term>
   <listitem>
    <para>
     driver callbacks struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     MPT protocol driver index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-device-driver-deregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_device_driver_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_device_driver_deregister</refname>
 <refpurpose>
     DeRegister device driver hooks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_device_driver_deregister </function></funcdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     MPT protocol driver index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-get-msg-frame">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_get_msg_frame</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_get_msg_frame</refname>
 <refpurpose>
     Obtain an MPT request frame from the pool
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>MPT_FRAME_HDR* <function>mpt_get_msg_frame </function></funcdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     Handle of registered MPT protocol driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Obtain an MPT request frame from the pool (of 1024) that are
   allocated per MPT adapter.
   </para><para>

   Returns pointer to a MPT request frame or <constant>NULL</constant> if none are available
   or IOC is not active.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-put-msg-frame">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_put_msg_frame</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_put_msg_frame</refname>
 <refpurpose>
     Send a protocol-specific MPT request frame to an IOC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_put_msg_frame </function></funcdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     Handle of registered MPT protocol driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine posts an MPT request frame to the request post FIFO of a
   specific MPT adapter.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-put-msg-frame-hi-pri">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_put_msg_frame_hi_pri</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_put_msg_frame_hi_pri</refname>
 <refpurpose>
     Send a hi-pri protocol-specific MPT request frame
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_put_msg_frame_hi_pri </function></funcdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     Handle of registered MPT protocol driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send a protocol-specific MPT request frame to an IOC using
   hi-priority request queue.
   </para><para>

   This routine posts an MPT request frame to the request post FIFO of a
   specific MPT adapter.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-free-msg-frame">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_free_msg_frame</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_free_msg_frame</refname>
 <refpurpose>
     Place MPT request frame back on FreeQ.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_free_msg_frame </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places a MPT request frame back on the MPT adapter's
   FreeQ.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-send-handshake-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_send_handshake_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_send_handshake_request</refname>
 <refpurpose>
     Send MPT request via doorbell handshake method.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_send_handshake_request </function></funcdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>reqBytes</parameter></paramdef>
   <paramdef>u32 * <parameter>req</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     Handle of registered MPT protocol driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reqBytes</parameter></term>
   <listitem>
    <para>
     Size of the request in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Use schedule if CAN_SLEEP else use udelay.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is used exclusively to send MptScsiTaskMgmt
   requests since they are required to be sent via doorbell handshake.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   It is the callers responsibility to byte-swap fields in the
   request which are greater than 1 byte in size.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-verify-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_verify_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_verify_adapter</refname>
 <refpurpose>
     Given IOC identifier, set pointer to its adapter structure.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_verify_adapter </function></funcdef>
   <paramdef>int <parameter>iocid</parameter></paramdef>
   <paramdef>MPT_ADAPTER ** <parameter>iocpp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>iocid</parameter></term>
   <listitem>
    <para>
     IOC unique identifier (integer)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>iocpp</parameter></term>
   <listitem>
    <para>
     Pointer to pointer to IOC adapter
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a unique IOC identifier, set pointer to the associated MPT
   adapter structure.
   </para><para>

   Returns iocid and sets iocpp if iocid is found.
   Returns -1 if iocid is not found.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-attach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_attach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_attach</refname>
 <refpurpose>
     Install a PCI intelligent MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_attach </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>const struct pci_device_id * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to pci_dev structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     PCI device ID information
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine performs all the steps necessary to bring the IOC of
   a MPT adapter to a OPERATIONAL state.  This includes registering
   memory regions, registering the interrupt, and allocating request
   and reply memory pools.
   </para><para>

   This routine also pre-fetches the LAN MAC address of a Fibre Channel
   MPT adapter.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
<refsect1>
<title>TODO</title>
<para>
   Add support for polled controllers
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-detach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_detach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_detach</refname>
 <refpurpose>
     Remove a PCI intelligent MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_detach </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to pci_dev structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_suspend</refname>
 <refpurpose>
     Fusion MPT base driver suspend routine.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_suspend </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>pm_message_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to pci_dev structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     new state to enter
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-resume">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_resume</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_resume</refname>
 <refpurpose>
     Fusion MPT base driver resume routine.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_resume </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to pci_dev structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-GetIocState">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_GetIocState</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_GetIocState</refname>
 <refpurpose>
     Get the current state of a MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>mpt_GetIocState </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>cooked</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cooked</parameter></term>
   <listitem>
    <para>
     Request raw or cooked IOC state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns all IOC Doorbell register bits if cooked==0, else just the
   Doorbell bits in MPI_IOC_STATE_MASK.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-alloc-fw-memory">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_alloc_fw_memory</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_alloc_fw_memory</refname>
 <refpurpose>
     allocate firmware memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_alloc_fw_memory </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     total FW bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If memory has already been allocated, the same (cached) value
   is returned.
   </para><para>

   Return 0 if successful, or non-zero for failure
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-free-fw-memory">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_free_fw_memory</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_free_fw_memory</refname>
 <refpurpose>
     free firmware memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_free_fw_memory </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If alt_img is NULL, delete from ioc structure.
   Else, delete a secondary image in same format.
</para>
</refsect1>
</refentry>

<refentry id="API-mptbase-sas-persist-operation">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptbase_sas_persist_operation</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptbase_sas_persist_operation</refname>
 <refpurpose>
     Perform operation on SAS Persistent Table
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptbase_sas_persist_operation </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>persist_opcode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>persist_opcode</parameter></term>
   <listitem>
    <para>
     see below
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   MPI_SAS_OP_CLEAR_NOT_PRESENT - Free all persist TargetID mappings for
   devices not currently present.
   MPI_SAS_OP_CLEAR_ALL_PERSISTENT - Clear al persist TargetID mappings
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   Don't use not this function during interrupt time.
   </para><para>

   Returns 0 for success, non-zero error
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-raid-phys-disk-pg0">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_raid_phys_disk_pg0</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_raid_phys_disk_pg0</refname>
 <refpurpose>
     returns phys disk page zero
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_raid_phys_disk_pg0 </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>phys_disk_num</parameter></paramdef>
   <paramdef>RaidPhysDiskPage0_t * <parameter>phys_disk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to a Adapter Structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>phys_disk_num</parameter></term>
   <listitem>
    <para>
     io unit unique phys disk num generated by the ioc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>phys_disk</parameter></term>
   <listitem>
    <para>
     requested payload data returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success
   -EFAULT if read of config page header fails or data pointer not NULL
   -ENOMEM if pci_alloc failed
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-raid-phys-disk-get-num-paths">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_raid_phys_disk_get_num_paths</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_raid_phys_disk_get_num_paths</refname>
 <refpurpose>
     returns number paths associated to this phys_num
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_raid_phys_disk_get_num_paths </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>phys_disk_num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to a Adapter Structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>phys_disk_num</parameter></term>
   <listitem>
    <para>
     io unit unique phys disk num generated by the ioc
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   returns number paths
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-raid-phys-disk-pg1">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_raid_phys_disk_pg1</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_raid_phys_disk_pg1</refname>
 <refpurpose>
     returns phys disk page 1
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_raid_phys_disk_pg1 </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>phys_disk_num</parameter></paramdef>
   <paramdef>RaidPhysDiskPage1_t * <parameter>phys_disk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to a Adapter Structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>phys_disk_num</parameter></term>
   <listitem>
    <para>
     io unit unique phys disk num generated by the ioc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>phys_disk</parameter></term>
   <listitem>
    <para>
     requested payload data returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success
   -EFAULT if read of config page header fails or data pointer not NULL
   -ENOMEM if pci_alloc failed
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-findImVolumes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_findImVolumes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_findImVolumes</refname>
 <refpurpose>
     Identify IDs of hidden disks and RAID Volumes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_findImVolumes </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to a Adapter Strucutre
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success
   -EFAULT if read of config page header fails or data pointer not NULL
   -ENOMEM if pci_alloc failed
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_config</refname>
 <refpurpose>
     Generic function to issue config message
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_config </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>CONFIGPARMS * <parameter>pCfg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to an adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pCfg</parameter></term>
   <listitem>
    <para>
     Pointer to a configuration structure. Struct contains
     action, page address, direction, physical address
     and pointer to a configuration page header
     Page header is updated.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success
   -EPERM if not allowed due to ISR context
   -EAGAIN if no msg frames currently available
   -EFAULT for non-successful reply or no reply (timeout)
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-print-ioc-summary">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_print_ioc_summary</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_print_ioc_summary</refname>
 <refpurpose>
     Write ASCII summary of IOC to a buffer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_print_ioc_summary </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>char * <parameter>buffer</parameter></paramdef>
   <paramdef>int * <parameter>size</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
   <paramdef>int <parameter>showlan</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     Pointer to buffer where IOC summary info should be written
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Pointer to number of bytes we wrote (set by this routine)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     Offset at which to start writing in buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>showlan</parameter></term>
   <listitem>
    <para>
     Display LAN stuff?
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine writes (english readable) ASCII text, which represents
   a summary of IOC information, to a buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-set-taskmgmt-in-progress-flag">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_set_taskmgmt_in_progress_flag</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_set_taskmgmt_in_progress_flag</refname>
 <refpurpose>
     set flags associated with task management
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_set_taskmgmt_in_progress_flag </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for SUCCESS or -1 if FAILED.
   </para><para>

   If -1 is return, then it was not possible to set the flags
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-clear-taskmgmt-in-progress-flag">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_clear_taskmgmt_in_progress_flag</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_clear_taskmgmt_in_progress_flag</refname>
 <refpurpose>
     clear flags associated with task management
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_clear_taskmgmt_in_progress_flag </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-halt-firmware">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_halt_firmware</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_halt_firmware</refname>
 <refpurpose>
     Halts the firmware if it is operational and panic the kernel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_halt_firmware </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-Soft-Hard-ResetHandler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_Soft_Hard_ResetHandler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_Soft_Hard_ResetHandler</refname>
 <refpurpose>
     Try less expensive reset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_Soft_Hard_ResetHandler </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Indicates if sleep or schedule must be called.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for SUCCESS or -1 if FAILED.
   Try for softreset first, only if it fails go for expensive
   HardReset.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-HardResetHandler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_HardResetHandler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_HardResetHandler</refname>
 <refpurpose>
     Generic reset handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_HardResetHandler </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Indicates if sleep or schedule must be called.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Issues SCSI Task Management call based on input arg values.
   If TaskMgmt fails, returns associated SCSI request.
</para>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   _HardResetHandler can be invoked from an interrupt thread (timer)
   or a non-interrupt thread.  In the former, must not call <function>schedule</function>.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   A return of -1 is a FATAL error case, as it means a
   FW reload/initialization failed.
   </para><para>

   Returns 0 for SUCCESS or -1 if FAILED.
</para>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptbase.c -->
<refentry id="API-mpt-get-cb-idx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_get_cb_idx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_get_cb_idx</refname>
 <refpurpose>
  obtain cb_idx for registered driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u8 <function>mpt_get_cb_idx </function></funcdef>
   <paramdef>MPT_DRIVER_CLASS <parameter>dclass</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dclass</parameter></term>
   <listitem>
    <para>
     class driver enum
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns cb_idx, or zero means it wasn't found
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-is-discovery-complete">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_is_discovery_complete</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_is_discovery_complete</refname>
 <refpurpose>
     determine if discovery has completed
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_is_discovery_complete </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     per adatper instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 1 when discovery completed, else zero.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-remove-dead-ioc-func">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_remove_dead_ioc_func</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_remove_dead_ioc_func</refname>
 <refpurpose>
     kthread context to remove dead ioc
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_remove_dead_ioc_func </function></funcdef>
   <paramdef>void * <parameter>arg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>arg</parameter></term>
   <listitem>
    <para>
     input argument, used to derive ioc
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return 0 if controller is removed from pci subsystem.
   Return -1 for other case.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-fault-reset-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_fault_reset_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_fault_reset_work</refname>
 <refpurpose>
     work performed on workq after ioc fault
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_fault_reset_work </function></funcdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     input argument, used to derive ioc
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-interrupt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_interrupt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_interrupt</refname>
 <refpurpose>
     MPT adapter (IOC) specific interrupt handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>irqreturn_t <function>mpt_interrupt </function></funcdef>
   <paramdef>int <parameter>irq</parameter></paramdef>
   <paramdef>void * <parameter>bus_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     irq number (not used)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bus_id</parameter></term>
   <listitem>
    <para>
     bus identifier cookie == pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is registered via the <function>request_irq</function> kernel API call,
   and handles all interrupts generated from a specific MPT adapter
   (also referred to as a IO Controller or IOC).
   This routine must clear the interrupt from the adapter and does
   so by reading the reply FIFO.  Multiple replies may be processed
   per single call to this routine.
   </para><para>

   This routine handles register-level access of the adapter but
   dispatches (calls) a protocol-specific callback routine to handle
   the protocol-specific details of the MPT request completion.
</para>
</refsect1>
</refentry>

<refentry id="API-mptbase-reply">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptbase_reply</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptbase_reply</refname>
 <refpurpose>
     MPT base driver's callback routine
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptbase_reply </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>req</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>reply</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     Pointer to original MPT request frame
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reply</parameter></term>
   <listitem>
    <para>
     Pointer to MPT reply frame (NULL if TurboReply)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   MPT base driver's callback routine; all base driver
   <quote>internal</quote> request/reply processing is routed here.
   Currently used for EventNotification and EventAck handling.
   </para><para>

   Returns 1 indicating original alloc'd request frame ptr
   should be freed, or 0 if it shouldn't.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-add-sge">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_add_sge</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_add_sge</refname>
 <refpurpose>
     Place a simple 32 bit SGE at address pAddr.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_add_sge </function></funcdef>
   <paramdef>void * <parameter>pAddr</parameter></paramdef>
   <paramdef>u32 <parameter>flagslength</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>dma_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pAddr</parameter></term>
   <listitem>
    <para>
     virtual address for SGE
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flagslength</parameter></term>
   <listitem>
    <para>
     SGE flags and data transfer length
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_addr</parameter></term>
   <listitem>
    <para>
     Physical address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places a MPT request frame back on the MPT adapter's
   FreeQ.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-add-sge-64bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_add_sge_64bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_add_sge_64bit</refname>
 <refpurpose>
     Place a simple 64 bit SGE at address pAddr.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_add_sge_64bit </function></funcdef>
   <paramdef>void * <parameter>pAddr</parameter></paramdef>
   <paramdef>u32 <parameter>flagslength</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>dma_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pAddr</parameter></term>
   <listitem>
    <para>
     virtual address for SGE
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flagslength</parameter></term>
   <listitem>
    <para>
     SGE flags and data transfer length
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_addr</parameter></term>
   <listitem>
    <para>
     Physical address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places a MPT request frame back on the MPT adapter's
   FreeQ.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-add-sge-64bit-1078">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_add_sge_64bit_1078</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_add_sge_64bit_1078</refname>
 <refpurpose>
     Place a simple 64 bit SGE at address pAddr (1078 workaround).
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_add_sge_64bit_1078 </function></funcdef>
   <paramdef>void * <parameter>pAddr</parameter></paramdef>
   <paramdef>u32 <parameter>flagslength</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>dma_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pAddr</parameter></term>
   <listitem>
    <para>
     virtual address for SGE
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flagslength</parameter></term>
   <listitem>
    <para>
     SGE flags and data transfer length
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_addr</parameter></term>
   <listitem>
    <para>
     Physical address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places a MPT request frame back on the MPT adapter's
   FreeQ.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-add-chain">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_add_chain</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_add_chain</refname>
 <refpurpose>
     Place a 32 bit chain SGE at address pAddr.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_add_chain </function></funcdef>
   <paramdef>void * <parameter>pAddr</parameter></paramdef>
   <paramdef>u8 <parameter>next</parameter></paramdef>
   <paramdef>u16 <parameter>length</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>dma_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pAddr</parameter></term>
   <listitem>
    <para>
     virtual address for SGE
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>next</parameter></term>
   <listitem>
    <para>
     nextChainOffset value (u32's)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     length of next SGL segment
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_addr</parameter></term>
   <listitem>
    <para>
     Physical address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-add-chain-64bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_add_chain_64bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_add_chain_64bit</refname>
 <refpurpose>
     Place a 64 bit chain SGE at address pAddr.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_add_chain_64bit </function></funcdef>
   <paramdef>void * <parameter>pAddr</parameter></paramdef>
   <paramdef>u8 <parameter>next</parameter></paramdef>
   <paramdef>u16 <parameter>length</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>dma_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pAddr</parameter></term>
   <listitem>
    <para>
     virtual address for SGE
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>next</parameter></term>
   <listitem>
    <para>
     nextChainOffset value (u32's)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     length of next SGL segment
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_addr</parameter></term>
   <listitem>
    <para>
     Physical address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-host-page-access-control">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_host_page_access_control</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_host_page_access_control</refname>
 <refpurpose>
     control the IOC's Host Page Buffer access
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_host_page_access_control </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>access_control_value</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>access_control_value</parameter></term>
   <listitem>
    <para>
     define bits below
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides mechanism for the host driver to control the IOC's
   Host Page Buffer access.
   </para><para>

   Access Control Value - bits[15:12]
   0h Reserved
   1h Enable Access { MPI_DB_HPBAC_ENABLE_ACCESS }
   2h Disable Access { MPI_DB_HPBAC_DISABLE_ACCESS }
   3h Free Buffer { MPI_DB_HPBAC_FREE_BUFFER }
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-host-page-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_host_page_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_host_page_alloc</refname>
 <refpurpose>
     allocate system memory for the fw
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_host_page_alloc </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>pIOCInit_t <parameter>ioc_init</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to pointer to IOC adapter
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc_init</parameter></term>
   <listitem>
    <para>
     Pointer to ioc init config page
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If we already allocated memory in past, then resend the same pointer.
   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-get-product-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_get_product_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_get_product_name</refname>
 <refpurpose>
     returns product string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char* <function>mpt_get_product_name </function></funcdef>
   <paramdef>u16 <parameter>vendor</parameter></paramdef>
   <paramdef>u16 <parameter>device</parameter></paramdef>
   <paramdef>u8 <parameter>revision</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vendor</parameter></term>
   <listitem>
    <para>
     pci vendor id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     pci device id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>revision</parameter></term>
   <listitem>
    <para>
     pci revision id
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns product string displayed when driver loads,
   in /proc/mpt/summary and /sysfs/class/scsi_host/host&lt;X&gt;/version_product
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-mapresources">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_mapresources</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_mapresources</refname>
 <refpurpose>
     map in memory mapped io
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_mapresources </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to pointer to IOC adapter
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-do-ioc-recovery">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_do_ioc_recovery</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_do_ioc_recovery</refname>
 <refpurpose>
     Initialize or recover MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_do_ioc_recovery </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>reason</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reason</parameter></term>
   <listitem>
    <para>
     Event word / reason
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Use schedule if CAN_SLEEP else use udelay.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine performs all the steps necessary to bring the IOC
   to a OPERATIONAL state.
   </para><para>

   This routine also pre-fetches the LAN MAC address of a Fibre Channel
   MPT adapter.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 for success
   -1 if failed to get board READY
   -2 if READY but IOCFacts Failed
   -3 if READY but PrimeIOCFifos Failed
   -4 if READY but IOCInit Failed
   -5 if failed to enable_device and/or request_selected_regions
   -6 if failed to upload firmware
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-detect-bound-ports">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_detect_bound_ports</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_detect_bound_ports</refname>
 <refpurpose>
     Search for matching PCI bus/dev_function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_detect_bound_ports </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to (struct pci_dev) structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Search for PCI bus/dev_function which matches
   PCI bus/dev_function (+/-1) for newly discovered 929,
   929X, 1030 or 1035.
   </para><para>

   If match on PCI dev_function +/-1 is found, bind the two MPT adapters
   using alt_ioc pointer fields in their <constant>MPT_ADAPTER</constant> structures.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-adapter-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_adapter_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_adapter_disable</refname>
 <refpurpose>
     Disable misbehaving MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_adapter_disable </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-adapter-dispose">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_adapter_dispose</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_adapter_dispose</refname>
 <refpurpose>
     Free all resources associated with an MPT adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_adapter_dispose </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine unregisters h/w resources and frees all alloc'd memory
   associated with a MPT adapter structure.
</para>
</refsect1>
</refentry>

<refentry id="API-MptDisplayIocCapabilities">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>MptDisplayIocCapabilities</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>MptDisplayIocCapabilities</refname>
 <refpurpose>
     Disply IOC's capabilities.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>MptDisplayIocCapabilities </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-MakeIocReady">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>MakeIocReady</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>MakeIocReady</refname>
 <refpurpose>
     Get IOC to a READY state, using KickStart if needed.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>MakeIocReady </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>force</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>force</parameter></term>
   <listitem>
    <para>
     Force hard KickStart of IOC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   1 - DIAG reset and READY
   0 - READY initially OR soft reset and READY
   -1 - Any failure on KickStart
   -2 - Msg Unit Reset Failed
   -3 - IO Unit Reset Failed
   -4 - IOC owned by a PEER
</para>
</refsect1>
</refentry>

<refentry id="API-GetIocFacts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>GetIocFacts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>GetIocFacts</refname>
 <refpurpose>
     Send IOCFacts request to MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>GetIocFacts </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
   <paramdef>int <parameter>reason</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reason</parameter></term>
   <listitem>
    <para>
     If recovery, only update facts.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-GetPortFacts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>GetPortFacts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>GetPortFacts</refname>
 <refpurpose>
     Send PortFacts request to MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>GetPortFacts </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>portnum</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>portnum</parameter></term>
   <listitem>
    <para>
     Port number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-SendIocInit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>SendIocInit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>SendIocInit</refname>
 <refpurpose>
     Send IOCInit request to MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>SendIocInit </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send IOCInit followed by PortEnable to bring IOC to OPERATIONAL state.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-SendPortEnable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>SendPortEnable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>SendPortEnable</refname>
 <refpurpose>
     Send PortEnable request to MPT adapter port.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>SendPortEnable </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>portnum</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>portnum</parameter></term>
   <listitem>
    <para>
     Port number to enable
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send PortEnable to bring IOC to OPERATIONAL state.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-do-upload">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_do_upload</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_do_upload</refname>
 <refpurpose>
     Construct and Send FWUpload request to MPT adapter port.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_do_upload </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success, &gt;0 for handshake failure
   &lt;0 for fw upload failure.
</para>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   If bound IOC and a successful FWUpload was performed
   on the bound IOC, the second image is discarded
   and memory is free'd. Both channels must upload to prevent
   IOC from running in degraded mode.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-downloadboot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_downloadboot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_downloadboot</refname>
 <refpurpose>
     DownloadBoot code
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_downloadboot </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MpiFwHeader_t * <parameter>pFwHeader</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pFwHeader</parameter></term>
   <listitem>
    <para>
     Pointer to firmware header info
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   FwDownloadBoot requires Programmed IO access.
   </para><para>

   Returns 0 for success
   -1 FW Image size is 0
   -2 No valid cached_fw Pointer
   &lt;0 for fw upload failure.
</para>
</refsect1>
</refentry>

<refentry id="API-KickStart">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>KickStart</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>KickStart</refname>
 <refpurpose>
     Perform hard reset of MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>KickStart </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>force</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>force</parameter></term>
   <listitem>
    <para>
     Force hard reset
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places MPT adapter in diagnostic mode via the
   WriteSequence register, and then performs a hard reset of adapter
   via the Diagnostic register.
</para>
</refsect1>
<refsect1>
<title>Inputs</title>
<para>
   sleepflag - CAN_SLEEP (non-interrupt thread)
   or NO_SLEEP (interrupt thread, use mdelay)
   force - 1 if doorbell active, board fault state
   board operational, IOC_RECOVERY or
   IOC_BRINGUP and there is an alt_ioc.
   0 else
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   1 - hard reset, READY
   0 - no reset due to History bit, READY
   -1 - no reset due to History bit but not READY
   OR reset but failed to come READY
   -2 - no reset, could not enter DIAG mode
   -3 - reset but bad FW bit
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-diag-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_diag_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_diag_reset</refname>
 <refpurpose>
     Perform hard reset of the adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_diag_reset </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>ignore</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ignore</parameter></term>
   <listitem>
    <para>
     Set if to honor and clear to ignore
     the reset history bit
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     CAN_SLEEP if called in a non-interrupt thread,
     else set to NO_SLEEP (use mdelay instead)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places the adapter in diagnostic mode via the
   WriteSequence register and then performs a hard reset of adapter
   via the Diagnostic register. Adapter should be in ready state
   upon successful completion.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   1  hard reset successful
   0  no reset performed because reset history bit set
   -2  enabling diagnostic mode failed
   -3  diagnostic reset failed
</para>
</refsect1>
</refentry>

<refentry id="API-SendIocReset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>SendIocReset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>SendIocReset</refname>
 <refpurpose>
     Send IOCReset request to MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>SendIocReset </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>reset_type</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reset_type</parameter></term>
   <listitem>
    <para>
     reset type, expected values are
     <constant>MPI_FUNCTION_IOC_MESSAGE_UNIT_RESET</constant> or <constant>MPI_FUNCTION_IO_UNIT_RESET</constant>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send IOCReset request to the MPT adapter.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-initChainBuffers">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>initChainBuffers</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>initChainBuffers</refname>
 <refpurpose>
     Allocate memory for and initialize chain buffers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>initChainBuffers </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates memory for and initializes chain buffers,
   chain buffer control arrays and spinlock.
</para>
</refsect1>
</refentry>

<refentry id="API-PrimeIocFifos">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>PrimeIocFifos</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>PrimeIocFifos</refname>
 <refpurpose>
     Initialize IOC request and reply FIFOs.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>PrimeIocFifos </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine allocates memory for the MPT reply and request frame
   pools (if necessary), and primes the IOC reply FIFO with
   reply frames.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-handshake-req-reply-wait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_handshake_req_reply_wait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_handshake_req_reply_wait</refname>
 <refpurpose>
     Send MPT request to and receive reply from IOC via doorbell handshake method.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_handshake_req_reply_wait </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>reqBytes</parameter></paramdef>
   <paramdef>u32 * <parameter>req</parameter></paramdef>
   <paramdef>int <parameter>replyBytes</parameter></paramdef>
   <paramdef>u16 * <parameter>u16reply</parameter></paramdef>
   <paramdef>int <parameter>maxwait</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reqBytes</parameter></term>
   <listitem>
    <para>
     Size of the request in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>replyBytes</parameter></term>
   <listitem>
    <para>
     Expected size of the reply in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>u16reply</parameter></term>
   <listitem>
    <para>
     Pointer to area where reply should be written
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maxwait</parameter></term>
   <listitem>
    <para>
     Max wait time for a reply (in seconds)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   It is the callers responsibility to byte-swap fields in the
   request which are greater than 1 byte in size.  It is also the
   callers responsibility to byte-swap response fields which are
   greater than 1 byte in size.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-WaitForDoorbellAck">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>WaitForDoorbellAck</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>WaitForDoorbellAck</refname>
 <refpurpose>
     Wait for IOC doorbell handshake acknowledge
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>WaitForDoorbellAck </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>howlong</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>howlong</parameter></term>
   <listitem>
    <para>
     How long to wait (in seconds)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine waits (up to ~2 seconds max) for IOC doorbell
   handshake ACKnowledge, indicated by the IOP_DOORBELL_STATUS
   bit in its IntStatus register being clear.
   </para><para>

   Returns a negative value on failure, else wait loop count.
</para>
</refsect1>
</refentry>

<refentry id="API-WaitForDoorbellInt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>WaitForDoorbellInt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>WaitForDoorbellInt</refname>
 <refpurpose>
     Wait for IOC to set its doorbell interrupt bit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>WaitForDoorbellInt </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>howlong</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>howlong</parameter></term>
   <listitem>
    <para>
     How long to wait (in seconds)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine waits (up to ~2 seconds max) for IOC doorbell interrupt
   (MPI_HIS_DOORBELL_INTERRUPT) to be set in the IntStatus register.
   </para><para>

   Returns a negative value on failure, else wait loop count.
</para>
</refsect1>
</refentry>

<refentry id="API-WaitForDoorbellReply">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>WaitForDoorbellReply</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>WaitForDoorbellReply</refname>
 <refpurpose>
     Wait for and capture an IOC handshake reply.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>WaitForDoorbellReply </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>howlong</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>howlong</parameter></term>
   <listitem>
    <para>
     How long to wait (in seconds)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine polls the IOC for a handshake reply, 16 bits at a time.
   Reply is cached to IOC private area large enough to hold a maximum
   of 128 bytes of reply data.
   </para><para>

   Returns a negative value on failure, else size of reply in WORDS.
</para>
</refsect1>
</refentry>

<refentry id="API-GetLanConfigPages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>GetLanConfigPages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>GetLanConfigPages</refname>
 <refpurpose>
     Fetch LANConfig pages.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>GetLanConfigPages </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 for success
   -ENOMEM if no memory available
   -EPERM if not allowed due to ISR context
   -EAGAIN if no msg frames currently available
   -EFAULT for non-successful reply or no reply (timeout)
</para>
</refsect1>
</refentry>

<refentry id="API-GetIoUnitPage2">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>GetIoUnitPage2</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>GetIoUnitPage2</refname>
 <refpurpose>
     Retrieve BIOS version and boot order information.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>GetIoUnitPage2 </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 for success
   -ENOMEM if no memory available
   -EPERM if not allowed due to ISR context
   -EAGAIN if no msg frames currently available
   -EFAULT for non-successful reply or no reply (timeout)
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-GetScsiPortSettings">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_GetScsiPortSettings</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_GetScsiPortSettings</refname>
 <refpurpose>
     read SCSI Port Page 0 and 2
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_GetScsiPortSettings </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>portnum</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to a Adapter Strucutre
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>portnum</parameter></term>
   <listitem>
    <para>
     IOC port number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   -EFAULT if read of config page header fails
   or if no nvram
   If read of SCSI Port Page 0 fails,
   NVRAM = MPT_HOST_NVRAM_INVALID  (0xFFFFFFFF)
</para>
</refsect1>
<refsect1>
<title>Adapter settings</title>
<para>
   async, narrow
   Return 1
   If read of SCSI Port Page 2 fails,
   Adapter settings valid
   NVRAM = MPT_HOST_NVRAM_INVALID  (0xFFFFFFFF)
   Return 1
   Else
   Both valid
   Return 0
   CHECK - what type of locking mechanisms should be used????
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-readScsiDevicePageHeaders">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_readScsiDevicePageHeaders</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_readScsiDevicePageHeaders</refname>
 <refpurpose>
     save version and length of SDP1
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_readScsiDevicePageHeaders </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>portnum</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to a Adapter Strucutre
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>portnum</parameter></term>
   <listitem>
    <para>
     IOC port number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   -EFAULT if read of config page header fails
   or 0 if success.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-inactive-raid-list-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_inactive_raid_list_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_inactive_raid_list_free</refname>
 <refpurpose>
     This clears this link list.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_inactive_raid_list_free </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     pointer to per adapter structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-inactive-raid-volumes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_inactive_raid_volumes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_inactive_raid_volumes</refname>
 <refpurpose>
     sets up link list of phy_disk_nums for devices belonging in an inactive volume
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_inactive_raid_volumes </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>channel</parameter></paramdef>
   <paramdef>u8 <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     pointer to per adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>channel</parameter></term>
   <listitem>
    <para>
     volume channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     volume target id
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-SendEventNotification">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>SendEventNotification</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>SendEventNotification</refname>
 <refpurpose>
     Send EventNotification (on or off) request to adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>SendEventNotification </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>EvSwitch</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>EvSwitch</parameter></term>
   <listitem>
    <para>
     Event switch flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-SendEventAck">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>SendEventAck</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>SendEventAck</refname>
 <refpurpose>
     Send EventAck request to MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>SendEventAck </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>EventNotificationReply_t * <parameter>evnp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>evnp</parameter></term>
   <listitem>
    <para>
     Pointer to original EventNotification request
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-ioc-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_ioc_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_ioc_reset</refname>
 <refpurpose>
     Base cleanup for hard reset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_ioc_reset </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>reset_phase</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to the adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reset_phase</parameter></term>
   <listitem>
    <para>
     Indicates pre- or post-reset functionality
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   Frees resources with internally generated commands.
</para>
</refsect1>
</refentry>

<refentry id="API-procmpt-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>procmpt_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>procmpt_create</refname>
 <refpurpose>
     Create <constant>MPT_PROCFS_MPTBASEDIR</constant> entries.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>procmpt_create </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-procmpt-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>procmpt_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>procmpt_destroy</refname>
 <refpurpose>
     Tear down <constant>MPT_PROCFS_MPTBASEDIR</constant> entries.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>procmpt_destroy </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-SoftResetHandler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_SoftResetHandler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_SoftResetHandler</refname>
 <refpurpose>
     Issues a less expensive reset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_SoftResetHandler </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Indicates if sleep or schedule must be called.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for SUCCESS or -1 if FAILED.
   </para><para>

   Message Unit Reset - instructs the IOC to reset the Reply Post and
   Free FIFO's. All the Message Frames on Reply Free FIFO are discarded.
   All posted buffers are freed, and event notification is turned off.
   IOC doesn't reply to any outstanding request. This will transfer IOC
   to READY state.
</para>
</refsect1>
</refentry>

<refentry id="API-ProcessEventNotification">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ProcessEventNotification</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ProcessEventNotification</refname>
 <refpurpose>
     Route EventNotificationReply to all event handlers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ProcessEventNotification </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>EventNotificationReply_t * <parameter>pEventReply</parameter></paramdef>
   <paramdef>int * <parameter>evHandlers</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pEventReply</parameter></term>
   <listitem>
    <para>
     Pointer to EventNotification reply frame
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>evHandlers</parameter></term>
   <listitem>
    <para>
     Pointer to integer, number of event handlers
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Routes a received EventNotificationReply to all currently registered
   event handlers.
   Returns sum of event handlers return values.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-fc-log-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_fc_log_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_fc_log_info</refname>
 <refpurpose>
     Log information returned from Fibre Channel IOC.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_fc_log_info </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>log_info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>log_info</parameter></term>
   <listitem>
    <para>
     U32 LogInfo reply word from the IOC
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refer to lsi/mpi_log_fc.h.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-spi-log-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_spi_log_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_spi_log_info</refname>
 <refpurpose>
     Log information returned from SCSI Parallel IOC.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_spi_log_info </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>log_info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>log_info</parameter></term>
   <listitem>
    <para>
     U32 LogInfo word from the IOC
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refer to lsi/sp_log.h.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-sas-log-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_sas_log_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_sas_log_info</refname>
 <refpurpose>
     Log information returned from SAS IOC.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_sas_log_info </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>log_info</parameter></paramdef>
   <paramdef>u8 <parameter>cb_idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>log_info</parameter></term>
   <listitem>
    <para>
     U32 LogInfo reply word from the IOC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     callback function's handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refer to lsi/mpi_log_sas.h.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-iocstatus-info-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_iocstatus_info_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_iocstatus_info_config</refname>
 <refpurpose>
     IOCSTATUS information for config pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_iocstatus_info_config </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>ioc_status</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc_status</parameter></term>
   <listitem>
    <para>
     U32 IOCStatus word from IOC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refer to lsi/mpi.h.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-iocstatus-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_iocstatus_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_iocstatus_info</refname>
 <refpurpose>
     IOCSTATUS information returned from IOC.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_iocstatus_info </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>ioc_status</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc_status</parameter></term>
   <listitem>
    <para>
     U32 IOCStatus word from IOC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refer to lsi/mpi.h.
</para>
</refsect1>
</refentry>

<refentry id="API-fusion-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fusion_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fusion_init</refname>
 <refpurpose>
     Fusion MPT base driver initialization routine.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fusion_init </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-fusion-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fusion_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fusion_exit</refname>
 <refpurpose>
     Perform driver unload cleanup.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>fusion_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   This routine frees all resources associated with each MPT adapter
   and removes all <constant>MPT_PROCFS_MPTBASEDIR</constant> entries.
</para>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptscsih.c -->
<refentry id="API-mptscsih-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_info</refname>
 <refpurpose>
  Return information about MPT adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>mptscsih_info </function></funcdef>
   <paramdef>struct Scsi_Host * <parameter>SChost</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SChost</parameter></term>
   <listitem>
    <para>
     Pointer to Scsi_Host structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.info routine)
   </para><para>

   Returns pointer to buffer where information was written.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-qcmd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_qcmd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_qcmd</refname>
 <refpurpose>
     Primary Fusion MPT SCSI initiator IO start routine.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_qcmd </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     Pointer to scsi_cmnd structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.queuecommand routine)
   This is the primary SCSI IO start routine.  Create a MPI SCSIIORequest
   from a linux scsi_cmnd request and send it to the IOC.
   </para><para>

   Returns 0. (rtn value discarded by linux scsi mid-layer)
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-IssueTaskMgmt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_IssueTaskMgmt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_IssueTaskMgmt</refname>
 <refpurpose>
     Generic send Task Management function.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_IssueTaskMgmt </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>u8 <parameter>type</parameter></paramdef>
   <paramdef>u8 <parameter>channel</parameter></paramdef>
   <paramdef>u8 <parameter>id</parameter></paramdef>
   <paramdef>u64 <parameter>lun</parameter></paramdef>
   <paramdef>int <parameter>ctx2abort</parameter></paramdef>
   <paramdef>ulong <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_SCSI_HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     Task Management type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>channel</parameter></term>
   <listitem>
    <para>
     channel number for task management
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     Logical Target ID for reset (if appropriate)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lun</parameter></term>
   <listitem>
    <para>
     Logical Unit for reset (if appropriate)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ctx2abort</parameter></term>
   <listitem>
    <para>
     Context for the task to be aborted (if appropriate)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     timeout for task management control
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   _HardResetHandler can be invoked from an interrupt thread (timer)
   or a non-interrupt thread.  In the former, must not call <function>schedule</function>.
   </para><para>

   Not all fields are meaningfull for all task types.
   </para><para>

   Returns 0 for SUCCESS, or FAILED.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-abort">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_abort</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_abort</refname>
 <refpurpose>
     Abort linux scsi_cmnd routine, new_eh variant
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_abort </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     Pointer to scsi_cmnd structure, IO to be aborted
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.eh_abort_handler routine)
   </para><para>

   Returns SUCCESS or FAILED.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-dev-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_dev_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_dev_reset</refname>
 <refpurpose>
     Perform a SCSI TARGET_RESET! new_eh variant
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_dev_reset </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     Pointer to scsi_cmnd structure, IO which reset is due to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.eh_dev_reset_handler routine)
   </para><para>

   Returns SUCCESS or FAILED.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-bus-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_bus_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_bus_reset</refname>
 <refpurpose>
     Perform a SCSI BUS_RESET! new_eh variant
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_bus_reset </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     Pointer to scsi_cmnd structure, IO which reset is due to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.eh_bus_reset_handler routine)
   </para><para>

   Returns SUCCESS or FAILED.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-host-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_host_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_host_reset</refname>
 <refpurpose>
     Perform a SCSI host adapter RESET (new_eh variant)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_host_reset </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     Pointer to scsi_cmnd structure, IO which reset is due to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.eh_host_reset_handler routine)
   </para><para>

   Returns SUCCESS or FAILED.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-taskmgmt-complete">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_taskmgmt_complete</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_taskmgmt_complete</refname>
 <refpurpose>
     Registered with Fusion MPT base driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_taskmgmt_complete </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to SCSI task mgmt request frame
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mr</parameter></term>
   <listitem>
    <para>
     Pointer to SCSI task mgmt reply frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is called from mptbase.c::<function><link linkend="API-mpt-interrupt">mpt_interrupt</link></function> at the completion
   of any SCSI task management request.
   This routine is registered with the MPT (base) driver at driver
   load/init time via the <function><link linkend="API-mpt-register">mpt_register</link></function> API call.
   </para><para>

   Returns 1 indicating alloc'd request frame ptr should be freed.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-get-scsi-lookup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_get_scsi_lookup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_get_scsi_lookup</refname>
 <refpurpose>
     retrieves scmd entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct scsi_cmnd * <function>mptscsih_get_scsi_lookup </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>i</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     index into the array
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the scsi_cmd pointer
</para>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptscsih.c -->
<refentry id="API-mptscsih-info-scsiio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_info_scsiio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_info_scsiio</refname>
 <refpurpose>
  debug print info on reply frame
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptscsih_info_scsiio </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>struct scsi_cmnd * <parameter>sc</parameter></paramdef>
   <paramdef>SCSIIOReply_t * <parameter>pScsiReply</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sc</parameter></term>
   <listitem>
    <para>
     original scsi cmnd pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pScsiReply</parameter></term>
   <listitem>
    <para>
     Pointer to MPT reply frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   MPT_DEBUG_REPLY needs to be enabled to obtain this info
   </para><para>

   Refer to lsi/mpi.h.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-getclear-scsi-lookup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_getclear_scsi_lookup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_getclear_scsi_lookup</refname>
 <refpurpose>
     retrieves and clears scmd entry from ScsiLookup[] array list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct scsi_cmnd * <function>mptscsih_getclear_scsi_lookup </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>i</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     index into the array
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the scsi_cmd pointer
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-set-scsi-lookup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_set_scsi_lookup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_set_scsi_lookup</refname>
 <refpurpose>
     write a scmd entry into the ScsiLookup[] array list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptscsih_set_scsi_lookup </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>i</parameter></paramdef>
   <paramdef>struct scsi_cmnd * <parameter>scmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     index into the array
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>scmd</parameter></term>
   <listitem>
    <para>
     scsi_cmnd pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-SCPNT-TO-LOOKUP-IDX">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>SCPNT_TO_LOOKUP_IDX</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>SCPNT_TO_LOOKUP_IDX</refname>
 <refpurpose>
     searches for a given scmd in the ScsiLookup[] array list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>SCPNT_TO_LOOKUP_IDX </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>struct scsi_cmnd * <parameter>sc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sc</parameter></term>
   <listitem>
    <para>
     scsi_cmnd pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mptscsih-get-completion-code">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_get_completion_code</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_get_completion_code</refname>
 <refpurpose>
     get completion code from MPT request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_get_completion_code </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>req</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>reply</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     Pointer to original MPT request frame
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reply</parameter></term>
   <listitem>
    <para>
     Pointer to MPT reply frame (NULL if TurboReply)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mptscsih-do-cmd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_do_cmd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_do_cmd</refname>
 <refpurpose>
     Do internal command.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_do_cmd </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>INTERNAL_CMD * <parameter>io</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     MPT_SCSI_HOST pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>io</parameter></term>
   <listitem>
    <para>
     INTERNAL_CMD pointer.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Issue the specified internally generated command and do command
   specific cleanup. For bus scan / DV only.
</para>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   If command is Inquiry and status is good,
   initialize a target structure, save the data
</para>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   Single threaded access only.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   &lt; 0 if an illegal command or no resources
   </para><para>

   0 if good
   </para><para>

   &gt; 0 if command complete but some type of completion error.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-synchronize-cache">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_synchronize_cache</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_synchronize_cache</refname>
 <refpurpose>
     Send SYNCHRONIZE_CACHE to all disks.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptscsih_synchronize_cache </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>VirtDevice * <parameter>vdevice</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vdevice</parameter></term>
   <listitem>
    <para>
     virtual target device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Uses the ISR, but with special processing.
   MUST be single-threaded.
</para>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptctl.c -->
<refentry id="API-mptctl-syscall-down">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptctl_syscall_down</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptctl_syscall_down</refname>
 <refpurpose>
  Down the MPT adapter syscall semaphore.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptctl_syscall_down </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>nonblock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nonblock</parameter></term>
   <listitem>
    <para>
     boolean, non-zero if O_NONBLOCK is set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   All of the ioctl commands can potentially sleep, which is illegal
   with a spinlock held, thus we perform mutual exclusion here.
   </para><para>

   Returns negative errno on error, or zero for success.
</para>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptspi.c -->
<refentry id="API-mptspi-setTargetNegoParms">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_setTargetNegoParms</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_setTargetNegoParms</refname>
 <refpurpose>
  Update the target negotiation parameters
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptspi_setTargetNegoParms </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>VirtTarget * <parameter>target</parameter></paramdef>
   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI Host Structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>target</parameter></term>
   <listitem>
    <para>
     per target private data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sdev</parameter></term>
   <listitem>
    <para>
     SCSI device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Update the target negotiation parameters based on the the Inquiry
   data, adapter capabilities, and NVRAM settings.
</para>
</refsect1>
</refentry>

<refentry id="API-mptspi-writeIOCPage4">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_writeIOCPage4</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_writeIOCPage4</refname>
 <refpurpose>
     write IOC Page 4
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptspi_writeIOCPage4 </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>u8 <parameter>channel</parameter></paramdef>
   <paramdef>u8 <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI Host Structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>channel</parameter></term>
   <listitem>
    <para>
     channel number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     write IOC Page4 for this ID &amp; Bus
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   -EAGAIN if unable to obtain a Message Frame
   or 0 if success.
</para>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   We do not wait for a return, write pages sequentially.
</para>
</refsect1>
</refentry>

<refentry id="API-mptspi-initTarget">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_initTarget</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_initTarget</refname>
 <refpurpose>
     Target, LUN alloc/free functionality.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptspi_initTarget </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>VirtTarget * <parameter>vtarget</parameter></paramdef>
   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_SCSI_HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vtarget</parameter></term>
   <listitem>
    <para>
     per target private data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sdev</parameter></term>
   <listitem>
    <para>
     SCSI device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   It's only SAFE to call this routine if data points to
   sane &amp; valid STANDARD INQUIRY data!
   </para><para>

   Allocate and initialize memory for this target.
   Save inquiry data.
</para>
</refsect1>
</refentry>

<refentry id="API-mptspi-is-raid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_is_raid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_is_raid</refname>
 <refpurpose>
     Determines whether target is belonging to volume
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptspi_is_raid </function></funcdef>
   <paramdef>struct _MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>u32 <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     target device id
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   non-zero = true
   zero = false
</para>
</refsect1>
</refentry>

<refentry id="API-mptspi-print-write-nego">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_print_write_nego</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_print_write_nego</refname>
 <refpurpose>
     negotiation parameters debug info that is being sent
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptspi_print_write_nego </function></funcdef>
   <paramdef>struct _MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>struct scsi_target * <parameter>starget</parameter></paramdef>
   <paramdef>u32 <parameter>ii</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>starget</parameter></term>
   <listitem>
    <para>
     SCSI target
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ii</parameter></term>
   <listitem>
    <para>
     negotiation parameters
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mptspi-print-read-nego">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_print_read_nego</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_print_read_nego</refname>
 <refpurpose>
     negotiation parameters debug info that is being read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptspi_print_read_nego </function></funcdef>
   <paramdef>struct _MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>struct scsi_target * <parameter>starget</parameter></paramdef>
   <paramdef>u32 <parameter>ii</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>starget</parameter></term>
   <listitem>
    <para>
     SCSI target
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ii</parameter></term>
   <listitem>
    <para>
     negotiation parameters
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mptspi-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_init</refname>
 <refpurpose>
     Register MPT adapter(s) as SCSI host(s) with SCSI mid-layer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptspi_init </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mptspi-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_exit</refname>
 <refpurpose>
     Unregisters MPT adapter(s)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>mptspi_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptfc.c -->
<refentry id="API-mptfc-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptfc_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptfc_init</refname>
 <refpurpose>
  Register MPT adapter(s) as SCSI host(s) with SCSI mid-layer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptfc_init </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mptfc-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptfc_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptfc_remove</refname>
 <refpurpose>
     Remove fc infrastructure for devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptfc_remove </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to pci_dev structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mptfc-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptfc_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptfc_exit</refname>
 <refpurpose>
     Unregisters MPT adapter(s)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>mptfc_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptlan.c -->
<refentry id="API-lan-reply">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>lan_reply</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>lan_reply</refname>
 <refpurpose>
  Handle all data sent from the hardware.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>lan_reply </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>reply</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to original MPT request frame (NULL if TurboReply)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reply</parameter></term>
   <listitem>
    <para>
     Pointer to MPT reply frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 1 indicating original alloc'd request frame ptr
   should be freed, or 0 if it shouldn't.
</para>
</refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="snddev">
     <title>Sound Devices</title>
<!-- include/sound/core.h -->
<refentry id="API-snd-printk">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_printk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_printk</refname>
 <refpurpose>
  printk wrapper
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_printk </function></funcdef>
   <paramdef> <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>args...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Works like <function><link linkend="API-printk">printk</link></function> but prints the file and the line of the caller
   when configured with CONFIG_SND_VERBOSE_PRINTK.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-printd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_printd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_printd</refname>
 <refpurpose>
     debug printk
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_printd </function></funcdef>
   <paramdef> <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>args...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Works like <function><link linkend="API-snd-printk">snd_printk</link></function> for debugging purposes.
   Ignored when CONFIG_SND_DEBUG is not set.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-BUG">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_BUG</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_BUG</refname>
 <refpurpose>
     give a BUG warning message and stack trace
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_BUG </function></funcdef>
  <void/>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <para>
  None
 </para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Calls <function>WARN</function> if CONFIG_SND_DEBUG is set.
   Ignored when CONFIG_SND_DEBUG is not set.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-printd-ratelimit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_printd_ratelimit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_printd_ratelimit</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_printd_ratelimit </function></funcdef>
  <void/>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <para>
  None
 </para>
</refsect1>
</refentry>

<refentry id="API-snd-BUG-ON">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_BUG_ON</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_BUG_ON</refname>
 <refpurpose>
     debugging check macro
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_BUG_ON </function></funcdef>
   <paramdef> <parameter>cond</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition to evaluate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Has the same behavior as WARN_ON when CONFIG_SND_DEBUG is set,
   otherwise just evaluates the conditional and returns the value.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-printdd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_printdd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_printdd</refname>
 <refpurpose>
     debug printk
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_printdd </function></funcdef>
   <paramdef> <parameter>format</parameter></paramdef>
   <paramdef> <parameter>args...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Works like <function><link linkend="API-snd-printk">snd_printk</link></function> for debugging purposes.
   Ignored when CONFIG_SND_DEBUG_VERBOSE is not set.
</para>
</refsect1>
</refentry>

<!-- sound/sound_core.c -->
<refentry id="API-register-sound-special-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_sound_special_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_sound_special_device</refname>
 <refpurpose>
  register a special sound node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_sound_special_device </function></funcdef>
   <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
   <paramdef>int <parameter>unit</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fops</parameter></term>
   <listitem>
    <para>
     File operations for the driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>unit</parameter></term>
   <listitem>
    <para>
     Unit number to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a special sound device by minor number from the sound
   subsystem.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The allocated number is returned on success. On failure,
   a negative error code is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-register-sound-mixer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_sound_mixer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_sound_mixer</refname>
 <refpurpose>
     register a mixer device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_sound_mixer </function></funcdef>
   <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
   <paramdef>int <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fops</parameter></term>
   <listitem>
    <para>
     File operations for the driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a mixer device. Unit is the number of the mixer requested.
   Pass -1 to request the next free mixer unit.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   On success, the allocated number is returned. On failure,
   a negative error code is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-register-sound-midi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_sound_midi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_sound_midi</refname>
 <refpurpose>
     register a midi device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_sound_midi </function></funcdef>
   <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
   <paramdef>int <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fops</parameter></term>
   <listitem>
    <para>
     File operations for the driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a midi device. Unit is the number of the midi device requested.
   Pass -1 to request the next free midi unit.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   On success, the allocated number is returned. On failure,
   a negative error code is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-register-sound-dsp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_sound_dsp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_sound_dsp</refname>
 <refpurpose>
     register a DSP device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_sound_dsp </function></funcdef>
   <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
   <paramdef>int <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fops</parameter></term>
   <listitem>
    <para>
     File operations for the driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a DSP device. Unit is the number of the DSP requested.
   Pass -1 to request the next free DSP unit.
   </para><para>

   This function allocates both the audio and dsp device entries together
   and will always allocate them as a matching pair - eg dsp3/audio3
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   On success, the allocated number is returned. On failure,
   a negative error code is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-sound-special">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_sound_special</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_sound_special</refname>
 <refpurpose>
     unregister a special sound device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_sound_special </function></funcdef>
   <paramdef>int <parameter>unit</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>unit</parameter></term>
   <listitem>
    <para>
     unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release a sound device that was allocated with
   <function>register_sound_special</function>. The unit passed is the return value from
   the register function.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-sound-mixer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_sound_mixer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_sound_mixer</refname>
 <refpurpose>
     unregister a mixer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_sound_mixer </function></funcdef>
   <paramdef>int <parameter>unit</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>unit</parameter></term>
   <listitem>
    <para>
     unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release a sound device that was allocated with <function><link linkend="API-register-sound-mixer">register_sound_mixer</link></function>.
   The unit passed is the return value from the register function.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-sound-midi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_sound_midi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_sound_midi</refname>
 <refpurpose>
     unregister a midi device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_sound_midi </function></funcdef>
   <paramdef>int <parameter>unit</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>unit</parameter></term>
   <listitem>
    <para>
     unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release a sound device that was allocated with <function><link linkend="API-register-sound-midi">register_sound_midi</link></function>.
   The unit passed is the return value from the register function.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-sound-dsp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_sound_dsp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_sound_dsp</refname>
 <refpurpose>
     unregister a DSP device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_sound_dsp </function></funcdef>
   <paramdef>int <parameter>unit</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>unit</parameter></term>
   <listitem>
    <para>
     unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release a sound device that was allocated with <function><link linkend="API-register-sound-dsp">register_sound_dsp</link></function>.
   The unit passed is the return value from the register function.
   </para><para>

   Both of the allocated units are released together automatically.
</para>
</refsect1>
</refentry>

<!-- include/sound/pcm.h -->
<refentry id="API-snd-pcm-stream-linked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_stream_linked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_stream_linked</refname>
 <refpurpose>
  Check whether the substream is linked with others
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_stream_linked </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     substream to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if the given substream is being linked with others.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-stream-lock-irqsave">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_stream_lock_irqsave</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_stream_lock_irqsave</refname>
 <refpurpose>
     Lock the PCM stream
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_pcm_stream_lock_irqsave </function></funcdef>
   <paramdef> <parameter>substream</parameter></paramdef>
   <paramdef> <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     irq flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This locks the PCM stream like <function><link linkend="API-snd-pcm-stream-lock">snd_pcm_stream_lock</link></function> but with the local
   IRQ (only when nonatomic is false).  In nonatomic case, this is identical
   as <function><link linkend="API-snd-pcm-stream-lock">snd_pcm_stream_lock</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-group-for-each-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_group_for_each_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_group_for_each_entry</refname>
 <refpurpose>
     iterate over the linked substreams
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_pcm_group_for_each_entry </function></funcdef>
   <paramdef> <parameter>s</parameter></paramdef>
   <paramdef> <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     the iterator
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over the all linked substreams to the given <parameter>substream</parameter>.
   When <parameter>substream</parameter> isn't linked with any others, this gives returns <parameter>substream</parameter>
   itself once.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-running">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_running</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_running</refname>
 <refpurpose>
     Check whether the substream is in a running state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_running </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     substream to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if the given substream is in the state RUNNING, or in the
   state DRAINING for playback.
</para>
</refsect1>
</refentry>

<refentry id="API-bytes-to-samples">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bytes_to_samples</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bytes_to_samples</refname>
 <refpurpose>
     Unit conversion of the size from bytes to samples
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>bytes_to_samples </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>ssize_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-bytes-to-frames">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bytes_to_frames</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bytes_to_frames</refname>
 <refpurpose>
     Unit conversion of the size from bytes to frames
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>snd_pcm_sframes_t <function>bytes_to_frames </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>ssize_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-samples-to-bytes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>samples_to_bytes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>samples_to_bytes</refname>
 <refpurpose>
     Unit conversion of the size from samples to bytes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>samples_to_bytes </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>ssize_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size in samples
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-frames-to-bytes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>frames_to_bytes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>frames_to_bytes</refname>
 <refpurpose>
     Unit conversion of the size from frames to bytes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>frames_to_bytes </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>snd_pcm_sframes_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size in frames
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-frame-aligned">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>frame_aligned</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>frame_aligned</refname>
 <refpurpose>
     Check whether the byte size is aligned to frames
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>frame_aligned </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>ssize_t <parameter>bytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bytes</parameter></term>
   <listitem>
    <para>
     size in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-buffer-bytes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_buffer_bytes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_buffer_bytes</refname>
 <refpurpose>
     Get the buffer size of the current PCM in bytes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>snd_pcm_lib_buffer_bytes </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-period-bytes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_period_bytes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_period_bytes</refname>
 <refpurpose>
     Get the period size of the current PCM in bytes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>snd_pcm_lib_period_bytes </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-playback-avail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_playback_avail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_playback_avail</refname>
 <refpurpose>
     Get the available (writable) space for playback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>snd_pcm_uframes_t <function>snd_pcm_playback_avail </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Result is between 0 ... (boundary - 1)
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-capture-avail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_capture_avail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_capture_avail</refname>
 <refpurpose>
     Get the available (readable) space for capture
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>snd_pcm_uframes_t <function>snd_pcm_capture_avail </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Result is between 0 ... (boundary - 1)
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-playback-hw-avail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_playback_hw_avail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_playback_hw_avail</refname>
 <refpurpose>
     Get the queued space for playback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>snd_pcm_sframes_t <function>snd_pcm_playback_hw_avail </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-capture-hw-avail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_capture_hw_avail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_capture_hw_avail</refname>
 <refpurpose>
     Get the free space for capture
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>snd_pcm_sframes_t <function>snd_pcm_capture_hw_avail </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-playback-ready">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_playback_ready</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_playback_ready</refname>
 <refpurpose>
     check whether the playback buffer is available
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_playback_ready </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether enough free space is available on the playback buffer.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Non-zero if available, or zero if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-capture-ready">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_capture_ready</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_capture_ready</refname>
 <refpurpose>
     check whether the capture buffer is available
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_capture_ready </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether enough capture data is available on the capture buffer.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Non-zero if available, or zero if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-playback-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_playback_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_playback_data</refname>
 <refpurpose>
     check whether any data exists on the playback buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_playback_data </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether any data exists on the playback buffer.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Non-zero if any data exists, or zero if not. If stop_threshold
   is bigger or equal to boundary, then this function returns always non-zero.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-playback-empty">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_playback_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_playback_empty</refname>
 <refpurpose>
     check whether the playback buffer is empty
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_playback_empty </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether the playback buffer is empty.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Non-zero if empty, or zero if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-capture-empty">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_capture_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_capture_empty</refname>
 <refpurpose>
     check whether the capture buffer is empty
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_capture_empty </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether the capture buffer is empty.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Non-zero if empty, or zero if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-trigger-done">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_trigger_done</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_trigger_done</refname>
 <refpurpose>
     Mark the master substream
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_trigger_done </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>struct snd_pcm_substream * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     the linked master substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When multiple substreams of the same card are linked and the hardware
   supports the single-shot operation, the driver calls this in the loop
   in <function><link linkend="API-snd-pcm-group-for-each-entry">snd_pcm_group_for_each_entry</link></function> for marking the substream as <quote>done</quote>.
   Then most of trigger operations are performed only to the given master
   substream.
   </para><para>

   The trigger_master mark is cleared at timestamp updates at the end
   of trigger operations.
</para>
</refsect1>
</refentry>

<refentry id="API-params-channels">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>params_channels</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>params_channels</refname>
 <refpurpose>
     Get the number of channels from the hw params
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>params_channels </function></funcdef>
   <paramdef>const struct snd_pcm_hw_params * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     hw params
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-params-rate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>params_rate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>params_rate</refname>
 <refpurpose>
     Get the sample rate from the hw params
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>params_rate </function></funcdef>
   <paramdef>const struct snd_pcm_hw_params * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     hw params
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-params-period-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>params_period_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>params_period_size</refname>
 <refpurpose>
     Get the period size (in frames) from the hw params
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>params_period_size </function></funcdef>
   <paramdef>const struct snd_pcm_hw_params * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     hw params
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-params-periods">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>params_periods</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>params_periods</refname>
 <refpurpose>
     Get the number of periods from the hw params
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>params_periods </function></funcdef>
   <paramdef>const struct snd_pcm_hw_params * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     hw params
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-params-buffer-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>params_buffer_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>params_buffer_size</refname>
 <refpurpose>
     Get the buffer size (in frames) from the hw params
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>params_buffer_size </function></funcdef>
   <paramdef>const struct snd_pcm_hw_params * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     hw params
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-params-buffer-bytes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>params_buffer_bytes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>params_buffer_bytes</refname>
 <refpurpose>
     Get the buffer size (in bytes) from the hw params
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>params_buffer_bytes </function></funcdef>
   <paramdef>const struct snd_pcm_hw_params * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     hw params
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-single">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_single</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_single</refname>
 <refpurpose>
     Constrain parameter to a single value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_single </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>unsigned int <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     The hw_params variable to constrain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     The value to constrain to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Positive if the value is changed, zero if it's not changed, or a
   negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-format-cpu-endian">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_format_cpu_endian</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_format_cpu_endian</refname>
 <refpurpose>
     Check the PCM format is CPU-endian
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_format_cpu_endian </function></funcdef>
   <paramdef>snd_pcm_format_t <parameter>format</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     the format to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 if the given PCM format is CPU-endian, 0 if
   opposite, or a negative error code if endian not specified.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-set-runtime-buffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_set_runtime_buffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_set_runtime_buffer</refname>
 <refpurpose>
     Set the PCM runtime buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_set_runtime_buffer </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>struct snd_dma_buffer * <parameter>bufp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bufp</parameter></term>
   <listitem>
    <para>
     the buffer information, NULL to clear
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copy the buffer information to runtime-&gt;dma_buffer when <parameter>bufp</parameter> is non-NULL.
   Otherwise it clears the current buffer information.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-gettime">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_gettime</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_gettime</refname>
 <refpurpose>
     Fill the timespec depending on the timestamp mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_gettime </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>struct timespec * <parameter>tv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tv</parameter></term>
   <listitem>
    <para>
     timespec to fill
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-alloc-vmalloc-buffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_alloc_vmalloc_buffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_alloc_vmalloc_buffer</refname>
 <refpurpose>
     allocate virtual DMA buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_alloc_vmalloc_buffer </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the substream to allocate the buffer to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the requested buffer size, in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates the PCM substream buffer using <function>vmalloc</function>, i.e., the memory is
   contiguous in kernel virtual space, but not in physical memory.  Use this
   if the buffer is accessed by kernel code but not by device DMA.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 if the buffer was changed, 0 if not changed, or a negative error
   code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-alloc-vmalloc-32-buffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_alloc_vmalloc_32_buffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_alloc_vmalloc_32_buffer</refname>
 <refpurpose>
     allocate 32-bit-addressable buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_alloc_vmalloc_32_buffer </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the substream to allocate the buffer to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the requested buffer size, in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function works like <function><link linkend="API-snd-pcm-lib-alloc-vmalloc-buffer">snd_pcm_lib_alloc_vmalloc_buffer</link></function>, but uses
   <function>vmalloc_32</function>, i.e., the pages are allocated from 32-bit-addressable memory.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 if the buffer was changed, 0 if not changed, or a negative error
   code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-sgbuf-get-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_sgbuf_get_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_sgbuf_get_addr</refname>
 <refpurpose>
     Get the DMA address at the corresponding offset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>dma_addr_t <function>snd_pcm_sgbuf_get_addr </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned int <parameter>ofs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ofs</parameter></term>
   <listitem>
    <para>
     byte offset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-sgbuf-get-ptr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_sgbuf_get_ptr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_sgbuf_get_ptr</refname>
 <refpurpose>
     Get the virtual address at the corresponding offset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>snd_pcm_sgbuf_get_ptr </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned int <parameter>ofs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ofs</parameter></term>
   <listitem>
    <para>
     byte offset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-sgbuf-get-chunk-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_sgbuf_get_chunk_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_sgbuf_get_chunk_size</refname>
 <refpurpose>
     Compute the max size that fits within the contig. page from the given size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>snd_pcm_sgbuf_get_chunk_size </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned int <parameter>ofs</parameter></paramdef>
   <paramdef>unsigned int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ofs</parameter></term>
   <listitem>
    <para>
     byte offset
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     byte size to examine
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-mmap-data-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_mmap_data_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_mmap_data_open</refname>
 <refpurpose>
     increase the mmap counter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_mmap_data_open </function></funcdef>
   <paramdef>struct vm_area_struct * <parameter>area</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>area</parameter></term>
   <listitem>
    <para>
     VMA
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   PCM mmap callback should handle this counter properly
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-mmap-data-close">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_mmap_data_close</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_mmap_data_close</refname>
 <refpurpose>
     decrease the mmap counter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_mmap_data_close </function></funcdef>
   <paramdef>struct vm_area_struct * <parameter>area</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>area</parameter></term>
   <listitem>
    <para>
     VMA
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   PCM mmap callback should handle this counter properly
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-limit-isa-dma-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_limit_isa_dma_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_limit_isa_dma_size</refname>
 <refpurpose>
     Get the max size fitting with ISA DMA transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_limit_isa_dma_size </function></funcdef>
   <paramdef>int <parameter>dma</parameter></paramdef>
   <paramdef>size_t * <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dma</parameter></term>
   <listitem>
    <para>
     DMA number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     pointer to store the max size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-stream-str">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_stream_str</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_stream_str</refname>
 <refpurpose>
     Get a string naming the direction of a stream
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>snd_pcm_stream_str </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   A string naming the direction of the stream.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-chmap-substream">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_chmap_substream</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_chmap_substream</refname>
 <refpurpose>
     get the PCM substream assigned to the given chmap info
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_pcm_substream * <function>snd_pcm_chmap_substream </function></funcdef>
   <paramdef>struct snd_pcm_chmap * <parameter>info</parameter></paramdef>
   <paramdef>unsigned int <parameter>idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     chmap information
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>idx</parameter></term>
   <listitem>
    <para>
     the substream number index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pcm-format-to-bits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcm_format_to_bits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pcm_format_to_bits</refname>
 <refpurpose>
     Strong-typed conversion of pcm_format to bitwise
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u64 <function>pcm_format_to_bits </function></funcdef>
   <paramdef>snd_pcm_format_t <parameter>pcm_format</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm_format</parameter></term>
   <listitem>
    <para>
     PCM format
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- sound/core/pcm.c -->
<refentry id="API-snd-pcm-format-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_format_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_format_name</refname>
 <refpurpose>
  Return a name string for the given PCM format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>snd_pcm_format_name </function></funcdef>
   <paramdef>snd_pcm_format_t <parameter>format</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     PCM format
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-new-stream">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_new_stream</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_new_stream</refname>
 <refpurpose>
     create a new PCM stream
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_new_stream </function></funcdef>
   <paramdef>struct snd_pcm * <parameter>pcm</parameter></paramdef>
   <paramdef>int <parameter>stream</parameter></paramdef>
   <paramdef>int <parameter>substream_count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     the pcm instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>stream</parameter></term>
   <listitem>
    <para>
     the stream direction, SNDRV_PCM_STREAM_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>substream_count</parameter></term>
   <listitem>
    <para>
     the number of substreams
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new stream for the pcm.
   The corresponding stream on the pcm must have been empty before
   calling this, i.e. zero must be given to the argument of
   <function><link linkend="API-snd-pcm-new">snd_pcm_new</link></function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_new</refname>
 <refpurpose>
     create a new PCM instance
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_new </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>const char * <parameter>id</parameter></paramdef>
   <paramdef>int <parameter>device</parameter></paramdef>
   <paramdef>int <parameter>playback_count</parameter></paramdef>
   <paramdef>int <parameter>capture_count</parameter></paramdef>
   <paramdef>struct snd_pcm ** <parameter>rpcm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the id string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device index (zero based)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>playback_count</parameter></term>
   <listitem>
    <para>
     the number of substreams for playback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>capture_count</parameter></term>
   <listitem>
    <para>
     the number of substreams for capture
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rpcm</parameter></term>
   <listitem>
    <para>
     the pointer to store the new pcm instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new PCM instance.
   </para><para>

   The pcm operators have to be set afterwards to the new instance
   via <function><link linkend="API-snd-pcm-set-ops">snd_pcm_set_ops</link></function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-new-internal">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_new_internal</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_new_internal</refname>
 <refpurpose>
     create a new internal PCM instance
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_new_internal </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>const char * <parameter>id</parameter></paramdef>
   <paramdef>int <parameter>device</parameter></paramdef>
   <paramdef>int <parameter>playback_count</parameter></paramdef>
   <paramdef>int <parameter>capture_count</parameter></paramdef>
   <paramdef>struct snd_pcm ** <parameter>rpcm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the id string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device index (zero based - shared with normal PCMs)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>playback_count</parameter></term>
   <listitem>
    <para>
     the number of substreams for playback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>capture_count</parameter></term>
   <listitem>
    <para>
     the number of substreams for capture
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rpcm</parameter></term>
   <listitem>
    <para>
     the pointer to store the new pcm instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new internal PCM instance with no userspace device or procfs
   entries. This is used by ASoC Back End PCMs in order to create a PCM that
   will only be used internally by kernel drivers. i.e. it cannot be opened
   by userspace. It provides existing ASoC components drivers with a substream
   and access to any private data.
   </para><para>

   The pcm operators have to be set afterwards to the new instance
   via <function><link linkend="API-snd-pcm-set-ops">snd_pcm_set_ops</link></function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-notify">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_notify</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_notify</refname>
 <refpurpose>
     Add/remove the notify list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_notify </function></funcdef>
   <paramdef>struct snd_pcm_notify * <parameter>notify</parameter></paramdef>
   <paramdef>int <parameter>nfree</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>notify</parameter></term>
   <listitem>
    <para>
     PCM notify list
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nfree</parameter></term>
   <listitem>
    <para>
     0 = register, 1 = unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This adds the given notifier to the global list so that the callback is
   called for each registered PCM devices.  This exists only for PCM OSS
   emulation, so far.
</para>
</refsect1>
</refentry>

<!-- sound/core/device.c -->
<refentry id="API-snd-device-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_device_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_device_new</refname>
 <refpurpose>
  create an ALSA device component
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_device_new </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>enum snd_device_type <parameter>type</parameter></paramdef>
   <paramdef>void * <parameter>device_data</parameter></paramdef>
   <paramdef>struct snd_device_ops * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the device type, SNDRV_DEV_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device_data</parameter></term>
   <listitem>
    <para>
     the data pointer of this device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     the operator table
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new device component for the given data pointer.
   The device will be assigned to the card and managed together
   by the card.
   </para><para>

   The data pointer plays a role as the identifier, too, so the
   pointer address must be unique and unchanged.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-device-disconnect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_device_disconnect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_device_disconnect</refname>
 <refpurpose>
     disconnect the device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_device_disconnect </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>void * <parameter>device_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device_data</parameter></term>
   <listitem>
    <para>
     the data pointer to disconnect
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Turns the device into the disconnection state, invoking
   dev_disconnect callback, if the device was already registered.
   </para><para>

   Usually called from <function><link linkend="API-snd-card-disconnect">snd_card_disconnect</link></function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure or if the
   device not found.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-device-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_device_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_device_free</refname>
 <refpurpose>
     release the device from the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_device_free </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>void * <parameter>device_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device_data</parameter></term>
   <listitem>
    <para>
     the data pointer to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes the device from the list on the card and invokes the
   callbacks, dev_disconnect and dev_free, corresponding to the state.
   Then release the device.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-device-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_device_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_device_register</refname>
 <refpurpose>
     register the device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_device_register </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>void * <parameter>device_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device_data</parameter></term>
   <listitem>
    <para>
     the data pointer to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers the device which was already created via
   <function><link linkend="API-snd-device-new">snd_device_new</link></function>.  Usually this is called from <function><link linkend="API-snd-card-register">snd_card_register</link></function>,
   but it can be called later if any new devices are created after
   invocation of <function><link linkend="API-snd-card-register">snd_card_register</link></function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure or if the
   device not found.
</para>
</refsect1>
</refentry>

<!-- sound/core/info.c -->
<refentry id="API-snd-info-get-line">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_get_line</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_get_line</refname>
 <refpurpose>
  read one line from the procfs buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_info_get_line </function></funcdef>
   <paramdef>struct snd_info_buffer * <parameter>buffer</parameter></paramdef>
   <paramdef>char * <parameter>line</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     the procfs buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>line</parameter></term>
   <listitem>
    <para>
     the buffer to store
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     the max. buffer size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reads one line from the buffer and stores the string.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or 1 if error or EOF.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-info-get-str">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_get_str</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_get_str</refname>
 <refpurpose>
     parse a string token
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>snd_info_get_str </function></funcdef>
   <paramdef>char * <parameter>dest</parameter></paramdef>
   <paramdef>const char * <parameter>src</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dest</parameter></term>
   <listitem>
    <para>
     the buffer to store the string token
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     the original string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     the max. length of token - 1
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Parses the original string and copy a token to the given
   string buffer.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The updated pointer of the original string so that
   it can be used for the next call.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-info-create-module-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_create_module_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_create_module_entry</refname>
 <refpurpose>
     create an info entry for the given module
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_info_entry * <function>snd_info_create_module_entry </function></funcdef>
   <paramdef>struct module * <parameter>module</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct snd_info_entry * <parameter>parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>module</parameter></term>
   <listitem>
    <para>
     the module pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the file name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     the parent directory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new info entry and assigns it to the given module.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The pointer of the new instance, or <constant>NULL</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-info-create-card-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_create_card_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_create_card_entry</refname>
 <refpurpose>
     create an info entry for the given card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_info_entry * <function>snd_info_create_card_entry </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct snd_info_entry * <parameter>parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the file name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     the parent directory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new info entry and assigns it to the given card.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The pointer of the new instance, or <constant>NULL</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-info-free-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_free_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_free_entry</refname>
 <refpurpose>
     release the info entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_info_free_entry </function></funcdef>
   <paramdef>struct snd_info_entry * <parameter>entry</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>entry</parameter></term>
   <listitem>
    <para>
     the info entry
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases the info entry.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-info-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_register</refname>
 <refpurpose>
     register the info entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_info_register </function></funcdef>
   <paramdef>struct snd_info_entry * <parameter>entry</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>entry</parameter></term>
   <listitem>
    <para>
     the info entry
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers the proc info entry.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<!-- sound/core/rawmidi.c -->
<refentry id="API-snd-rawmidi-receive">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_receive</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_receive</refname>
 <refpurpose>
  receive the input data from the device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_receive </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
   <paramdef>const unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     the buffer pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the data size to read
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reads the data from the internal buffer.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The size of read data, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-transmit-empty">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_transmit_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_transmit_empty</refname>
 <refpurpose>
     check whether the output buffer is empty
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_transmit_empty </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 if the internal output buffer is empty, 0 if not.
</para>
</refsect1>
</refentry>

<refentry id="API---snd-rawmidi-transmit-peek">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__snd_rawmidi_transmit_peek</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__snd_rawmidi_transmit_peek</refname>
 <refpurpose>
     copy data from the internal buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__snd_rawmidi_transmit_peek </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     the buffer pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     data size to transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a variant of <function><link linkend="API-snd-rawmidi-transmit-peek">snd_rawmidi_transmit_peek</link></function> without spinlock.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-transmit-peek">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_transmit_peek</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_transmit_peek</refname>
 <refpurpose>
     copy data from the internal buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_transmit_peek </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     the buffer pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     data size to transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies data from the internal output buffer to the given buffer.
   </para><para>

   Call this in the interrupt handler when the midi output is ready,
   and call <function><link linkend="API-snd-rawmidi-transmit-ack">snd_rawmidi_transmit_ack</link></function> after the transmission is
   finished.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The size of copied data, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API---snd-rawmidi-transmit-ack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__snd_rawmidi_transmit_ack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__snd_rawmidi_transmit_ack</refname>
 <refpurpose>
     acknowledge the transmission
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__snd_rawmidi_transmit_ack </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the transferred count
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a variant of <function><link linkend="API---snd-rawmidi-transmit-ack">__snd_rawmidi_transmit_ack</link></function> without spinlock.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-transmit-ack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_transmit_ack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_transmit_ack</refname>
 <refpurpose>
     acknowledge the transmission
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_transmit_ack </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the transferred count
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Advances the hardware pointer for the internal output buffer with
   the given size and updates the condition.
   Call after the transmission is finished.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The advanced size if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-transmit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_transmit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_transmit</refname>
 <refpurpose>
     copy from the buffer to the device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_transmit </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     the buffer pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the data size to transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies data from the buffer to the device and advances the pointer.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The copied size if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_new</refname>
 <refpurpose>
     create a rawmidi instance
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_new </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>char * <parameter>id</parameter></paramdef>
   <paramdef>int <parameter>device</parameter></paramdef>
   <paramdef>int <parameter>output_count</parameter></paramdef>
   <paramdef>int <parameter>input_count</parameter></paramdef>
   <paramdef>struct snd_rawmidi ** <parameter>rrawmidi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the id string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>output_count</parameter></term>
   <listitem>
    <para>
     the number of output streams
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>input_count</parameter></term>
   <listitem>
    <para>
     the number of input streams
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rrawmidi</parameter></term>
   <listitem>
    <para>
     the pointer to store the new rawmidi instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new rawmidi instance.
   Use <function><link linkend="API-snd-rawmidi-set-ops">snd_rawmidi_set_ops</link></function> to set the operators to the new instance.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-set-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_set_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_set_ops</refname>
 <refpurpose>
     set the rawmidi operators
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_rawmidi_set_ops </function></funcdef>
   <paramdef>struct snd_rawmidi * <parameter>rmidi</parameter></paramdef>
   <paramdef>int <parameter>stream</parameter></paramdef>
   <paramdef>struct snd_rawmidi_ops * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rmidi</parameter></term>
   <listitem>
    <para>
     the rawmidi instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>stream</parameter></term>
   <listitem>
    <para>
     the stream direction, SNDRV_RAWMIDI_STREAM_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     the operator table
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets the rawmidi operators for the given stream direction.
</para>
</refsect1>
</refentry>

<!-- sound/core/sound.c -->
<refentry id="API-snd-request-card">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_request_card</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_request_card</refname>
 <refpurpose>
  try to load the card module
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_request_card </function></funcdef>
   <paramdef>int <parameter>card</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Tries to load the module <quote>snd-card-X</quote> for the given card number
   via request_module.  Returns immediately if already loaded.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-lookup-minor-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_lookup_minor_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_lookup_minor_data</refname>
 <refpurpose>
     get user data of a registered device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>snd_lookup_minor_data </function></funcdef>
   <paramdef>unsigned int <parameter>minor</parameter></paramdef>
   <paramdef>int <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>minor</parameter></term>
   <listitem>
    <para>
     the minor number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     device type (SNDRV_DEVICE_TYPE_XXX)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks that a minor device with the specified type is registered, and returns
   its user data pointer.
   </para><para>

   This function increments the reference counter of the card instance
   if an associated instance with the given minor number and type is found.
   The caller must call <function>snd_card_unref</function> appropriately later.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The user data pointer if the specified device is found. <constant>NULL</constant>
   otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-register-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_register_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_register_device</refname>
 <refpurpose>
     Register the ALSA device file for the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_register_device </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>int <parameter>dev</parameter></paramdef>
   <paramdef>const struct file_operations * <parameter>f_ops</parameter></paramdef>
   <paramdef>void * <parameter>private_data</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>device</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the device type, SNDRV_DEVICE_TYPE_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the device index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>f_ops</parameter></term>
   <listitem>
    <para>
     the file operations
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>private_data</parameter></term>
   <listitem>
    <para>
     user pointer for f_ops-&gt;<function>open</function>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers an ALSA device file for the given card.
   The operators have to be set in reg parameter.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-unregister-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_unregister_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_unregister_device</refname>
 <refpurpose>
     unregister the device on the given card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_unregister_device </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregisters the device file already registered via
   <function><link linkend="API-snd-register-device">snd_register_device</link></function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<!-- sound/core/memory.c -->
<refentry id="API-copy-to-user-fromio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>copy_to_user_fromio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>copy_to_user_fromio</refname>
 <refpurpose>
  copy data from mmio-space to user-space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>copy_to_user_fromio </function></funcdef>
   <paramdef>void __user * <parameter>dst</parameter></paramdef>
   <paramdef>const volatile void __iomem * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     the destination pointer on user-space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     the source pointer on mmio
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the data size to copy in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies the data from mmio-space to user-space.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or non-zero on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-copy-from-user-toio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>copy_from_user_toio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>copy_from_user_toio</refname>
 <refpurpose>
     copy data from user-space to mmio-space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>copy_from_user_toio </function></funcdef>
   <paramdef>volatile void __iomem * <parameter>dst</parameter></paramdef>
   <paramdef>const void __user * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     the destination pointer on mmio-space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     the source pointer on user-space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the data size to copy in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies the data from user-space to mmio-space.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or non-zero on failure.
</para>
</refsect1>
</refentry>

<!-- sound/core/pcm_memory.c -->
<refentry id="API-snd-pcm-lib-preallocate-free-for-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_preallocate_free_for_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_preallocate_free_for_all</refname>
 <refpurpose>
  release all pre-allocated buffers on the pcm
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_preallocate_free_for_all </function></funcdef>
   <paramdef>struct snd_pcm * <parameter>pcm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     the pcm instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases all the pre-allocated buffers on the given pcm.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-preallocate-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_preallocate_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_preallocate_pages</refname>
 <refpurpose>
     pre-allocation for the given DMA type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_preallocate_pages </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>size_t <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     DMA type (SNDRV_DMA_TYPE_*)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     DMA type dependent data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the requested pre-allocation size in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     the max. allowed pre-allocation size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Do pre-allocation for the given DMA buffer type.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-preallocate-pages-for-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_preallocate_pages_for_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_preallocate_pages_for_all</refname>
 <refpurpose>
     pre-allocation for continuous memory type (all substreams)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_preallocate_pages_for_all </function></funcdef>
   <paramdef>struct snd_pcm * <parameter>pcm</parameter></paramdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>size_t <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     the pcm instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     DMA type (SNDRV_DMA_TYPE_*)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     DMA type dependent data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the requested pre-allocation size in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     the max. allowed pre-allocation size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Do pre-allocation to all substreams of the given pcm for the
   specified DMA type.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-sgbuf-ops-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_sgbuf_ops_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_sgbuf_ops_page</refname>
 <refpurpose>
     get the page struct at the given offset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>snd_pcm_sgbuf_ops_page </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned long <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     the buffer offset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Used as the page callback of PCM ops.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The page struct at the given buffer offset. <constant>NULL</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-malloc-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_malloc_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_malloc_pages</refname>
 <refpurpose>
     allocate the DMA buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_malloc_pages </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the substream to allocate the DMA buffer to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the requested buffer size in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates the DMA buffer on the BUS type given earlier to
   <function>snd_pcm_lib_preallocate_xxx_pages</function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 if the buffer is changed, 0 if not changed, or a negative
   code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-free-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_free_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_free_pages</refname>
 <refpurpose>
     release the allocated DMA buffer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_free_pages </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the substream to release the DMA buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases the DMA buffer allocated via <function><link linkend="API-snd-pcm-lib-malloc-pages">snd_pcm_lib_malloc_pages</link></function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-free-vmalloc-buffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_free_vmalloc_buffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_free_vmalloc_buffer</refname>
 <refpurpose>
     free vmalloc buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_free_vmalloc_buffer </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the substream with a buffer allocated by
     <function><link linkend="API-snd-pcm-lib-alloc-vmalloc-buffer">snd_pcm_lib_alloc_vmalloc_buffer</link></function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-get-vmalloc-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_get_vmalloc_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_get_vmalloc_page</refname>
 <refpurpose>
     map vmalloc buffer offset to page struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>snd_pcm_lib_get_vmalloc_page </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned long <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the substream with a buffer allocated by
     <function><link linkend="API-snd-pcm-lib-alloc-vmalloc-buffer">snd_pcm_lib_alloc_vmalloc_buffer</link></function>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     offset in the buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is to be used as the page callback in the PCM ops.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The page struct, or <constant>NULL</constant> on failure.
</para>
</refsect1>
</refentry>

<!-- sound/core/init.c -->
<refentry id="API-snd-device-initialize">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_device_initialize</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_device_initialize</refname>
 <refpurpose>
  Initialize struct device for sound devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_device_initialize </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     card to assign, optional
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-card-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_new</refname>
 <refpurpose>
     create and initialize a soundcard structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_new </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>parent</parameter></paramdef>
   <paramdef>int <parameter>idx</parameter></paramdef>
   <paramdef>const char * <parameter>xid</parameter></paramdef>
   <paramdef>struct module * <parameter>module</parameter></paramdef>
   <paramdef>int <parameter>extra_size</parameter></paramdef>
   <paramdef>struct snd_card ** <parameter>card_ret</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     the parent device object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>idx</parameter></term>
   <listitem>
    <para>
     card index (address) [0 ... (SNDRV_CARDS-1)]
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>xid</parameter></term>
   <listitem>
    <para>
     card identification (ASCII string)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>module</parameter></term>
   <listitem>
    <para>
     top level module for locking
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>extra_size</parameter></term>
   <listitem>
    <para>
     allocate this extra size after the main soundcard structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>card_ret</parameter></term>
   <listitem>
    <para>
     the pointer to store the created card instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates and initializes a soundcard structure.
   </para><para>

   The function allocates snd_card instance via kzalloc with the given
   space for the driver to use freely.  The allocated struct is stored
   in the given card_ret pointer.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful or a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-card-disconnect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_disconnect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_disconnect</refname>
 <refpurpose>
     disconnect all APIs from the file-operations (user space)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_disconnect </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Disconnects all APIs from the file-operations (user space).
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero, otherwise a negative error code.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   The current implementation replaces all active file-&gt;f_op with special
   dummy file operations (they do nothing except release).
</para>
</refsect1>
</refentry>

<refentry id="API-snd-card-free-when-closed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_free_when_closed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_free_when_closed</refname>
 <refpurpose>
     Disconnect the card, free it later eventually
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_free_when_closed </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unlike <function><link linkend="API-snd-card-free">snd_card_free</link></function>, this function doesn't try to release the card
   resource immediately, but tries to disconnect at first.  When the card
   is still in use, the function returns before freeing the resources.
   The card resources will be freed when the refcount gets to zero.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-card-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_free</refname>
 <refpurpose>
     frees given soundcard structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_free </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function releases the soundcard structure and the all assigned
   devices automatically.  That is, you don't have to release the devices
   by yourself.
   </para><para>

   This function waits until the all resources are properly released.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero. Frees all associated devices and frees the control
   interface associated to given soundcard.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-card-set-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_set_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_set_id</refname>
 <refpurpose>
     set card identification name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_card_set_id </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>const char * <parameter>nid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nid</parameter></term>
   <listitem>
    <para>
     new identification string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function sets the card identification and checks for name
   collisions.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-card-add-dev-attr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_add_dev_attr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_add_dev_attr</refname>
 <refpurpose>
     Append a new sysfs attribute group to card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_add_dev_attr </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>const struct attribute_group * <parameter>group</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>group</parameter></term>
   <listitem>
    <para>
     attribute group to append
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-card-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_register</refname>
 <refpurpose>
     register the soundcard
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_register </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function registers all the devices assigned to the soundcard.
   Until calling this, the ALSA control interface is blocked from the
   external accesses.  Thus, you should call this function at the end
   of the initialization of the card.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero otherwise a negative error code if the registration failed.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-component-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_component_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_component_add</refname>
 <refpurpose>
     add a component string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_component_add </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>const char * <parameter>component</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>component</parameter></term>
   <listitem>
    <para>
     the component id string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function adds the component id string to the supported list.
   The component can be referred from the alsa-lib.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero otherwise a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-card-file-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_file_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_file_add</refname>
 <refpurpose>
     add the file to the file list of the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_file_add </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     file pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function adds the file to the file linked-list of the card.
   This linked-list is used to keep tracking the connection state,
   and to avoid the release of busy resources by hotplug.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero or a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-card-file-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_file_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_file_remove</refname>
 <refpurpose>
     remove the file from the file list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_file_remove </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     file pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function removes the file formerly added to the card via
   <function><link linkend="API-snd-card-file-add">snd_card_file_add</link></function> function.
   If all files are removed and <function><link linkend="API-snd-card-free-when-closed">snd_card_free_when_closed</link></function> was
   called beforehand, it processes the pending release of
   resources.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero or a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-power-wait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_power_wait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_power_wait</refname>
 <refpurpose>
     wait until the power-state is changed.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_power_wait </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>unsigned int <parameter>power_state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>power_state</parameter></term>
   <listitem>
    <para>
     expected power state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Waits until the power-state is changed.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the power lock must be active before call.
</para>
</refsect1>
</refentry>

<!-- sound/core/isadma.c -->
<refentry id="API-snd-dma-program">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_program</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_program</refname>
 <refpurpose>
  program an ISA DMA transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_dma_program </function></funcdef>
   <paramdef>unsigned long <parameter>dma</parameter></paramdef>
   <paramdef>unsigned long <parameter>addr</parameter></paramdef>
   <paramdef>unsigned int <parameter>size</parameter></paramdef>
   <paramdef>unsigned short <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dma</parameter></term>
   <listitem>
    <para>
     the dma number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     the physical address of the buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the DMA transfer size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the DMA transfer mode, DMA_MODE_XXX
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Programs an ISA DMA transfer for the given buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_disable</refname>
 <refpurpose>
     stop the ISA DMA transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_dma_disable </function></funcdef>
   <paramdef>unsigned long <parameter>dma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dma</parameter></term>
   <listitem>
    <para>
     the dma number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Stops the ISA DMA transfer.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-pointer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_pointer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_pointer</refname>
 <refpurpose>
     return the current pointer to DMA transfer buffer in bytes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>snd_dma_pointer </function></funcdef>
   <paramdef>unsigned long <parameter>dma</parameter></paramdef>
   <paramdef>unsigned int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dma</parameter></term>
   <listitem>
    <para>
     the dma number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the dma transfer size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The current pointer in DMA transfer buffer in bytes.
</para>
</refsect1>
</refentry>

<!-- sound/core/control.c -->
<refentry id="API-snd-ctl-notify">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_notify</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_notify</refname>
 <refpurpose>
  Send notification to user-space for a control change
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_ctl_notify </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>unsigned int <parameter>mask</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_id * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card to send notification
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     the event mask, SNDRV_CTL_EVENT_*
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the ctl element id to send notification
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function adds an event record with the given id and mask, appends
   to the list and wakes up the user-space for notification.  This can be
   called in the atomic context.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-new1">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_new1</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_new1</refname>
 <refpurpose>
     create a control instance from the template
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_kcontrol * <function>snd_ctl_new1 </function></funcdef>
   <paramdef>const struct snd_kcontrol_new * <parameter>ncontrol</parameter></paramdef>
   <paramdef>void * <parameter>private_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ncontrol</parameter></term>
   <listitem>
    <para>
     the initialization record
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>private_data</parameter></term>
   <listitem>
    <para>
     the private data to set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates a new struct snd_kcontrol instance and initialize from the given 
   template.  When the access field of ncontrol is 0, it's assumed as
   READWRITE access. When the count field is 0, it's assumes as one.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The pointer of the newly generated instance, or <constant>NULL</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-free-one">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_free_one</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_free_one</refname>
 <refpurpose>
     release the control instance
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_ctl_free_one </function></funcdef>
   <paramdef>struct snd_kcontrol * <parameter>kcontrol</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kcontrol</parameter></term>
   <listitem>
    <para>
     the control instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases the control instance created via <function>snd_ctl_new</function>
   or <function><link linkend="API-snd-ctl-new1">snd_ctl_new1</link></function>.
   Don't call this after the control was added to the card.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_add</refname>
 <refpurpose>
     add the control instance to the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_add </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_kcontrol * <parameter>kcontrol</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kcontrol</parameter></term>
   <listitem>
    <para>
     the control instance to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds the control instance created via <function>snd_ctl_new</function> or
   <function><link linkend="API-snd-ctl-new1">snd_ctl_new1</link></function> to the given card. Assigns also an unique
   numid used for fast search.
   </para><para>

   It frees automatically the control which cannot be added.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-replace">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_replace</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_replace</refname>
 <refpurpose>
     replace the control instance of the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_replace </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_kcontrol * <parameter>kcontrol</parameter></paramdef>
   <paramdef>bool <parameter>add_on_replace</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kcontrol</parameter></term>
   <listitem>
    <para>
     the control instance to replace
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>add_on_replace</parameter></term>
   <listitem>
    <para>
     add the control if not already added
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Replaces the given control.  If the given control does not exist
   and the add_on_replace flag is set, the control is added.  If the
   control exists, it is destroyed first.
   </para><para>

   It frees automatically the control which cannot be added or replaced.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_remove</refname>
 <refpurpose>
     remove the control from the card and release it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_remove </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_kcontrol * <parameter>kcontrol</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kcontrol</parameter></term>
   <listitem>
    <para>
     the control instance to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes the control from the card and then releases the instance.
   You don't need to call <function><link linkend="API-snd-ctl-free-one">snd_ctl_free_one</link></function>. You must be in
   the write lock - down_write(<structname>card</structname>-&gt;controls_rwsem).
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-remove-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_remove_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_remove_id</refname>
 <refpurpose>
     remove the control of the given id and release it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_remove_id </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_id * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the control id to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds the control instance with the given id, removes it from the
   card list and releases it.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-activate-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_activate_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_activate_id</refname>
 <refpurpose>
     activate/inactivate the control of the given id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_activate_id </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_id * <parameter>id</parameter></paramdef>
   <paramdef>int <parameter>active</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the control id to activate/inactivate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>active</parameter></term>
   <listitem>
    <para>
     non-zero to activate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds the control instance with the given id, and activate or
   inactivate the control together with notification, if changed.
   The given ID data is filled with full information.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 if unchanged, 1 if changed, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-rename-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_rename_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_rename_id</refname>
 <refpurpose>
     replace the id of a control on the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_rename_id </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_id * <parameter>src_id</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_id * <parameter>dst_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_id</parameter></term>
   <listitem>
    <para>
     the old id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dst_id</parameter></term>
   <listitem>
    <para>
     the new id
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds the control with the old id from the card, and replaces the
   id with the new one.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-find-numid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_find_numid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_find_numid</refname>
 <refpurpose>
     find the control instance with the given number-id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_kcontrol * <function>snd_ctl_find_numid </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>unsigned int <parameter>numid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>numid</parameter></term>
   <listitem>
    <para>
     the number-id to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds the control instance with the given number-id from the card.
   </para><para>

   The caller must down card-&gt;controls_rwsem before calling this function
   (if the race condition can happen).
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The pointer of the instance if found, or <constant>NULL</constant> if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-find-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_find_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_find_id</refname>
 <refpurpose>
     find the control instance with the given id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_kcontrol * <function>snd_ctl_find_id </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_id * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the id to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds the control instance with the given id from the card.
   </para><para>

   The caller must down card-&gt;controls_rwsem before calling this function
   (if the race condition can happen).
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The pointer of the instance if found, or <constant>NULL</constant> if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-register-ioctl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_register_ioctl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_register_ioctl</refname>
 <refpurpose>
     register the device-specific control-ioctls
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_register_ioctl </function></funcdef>
   <paramdef>snd_kctl_ioctl_func_t <parameter>fcn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fcn</parameter></term>
   <listitem>
    <para>
     ioctl callback function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   called from each device manager like pcm.c, hwdep.c, etc.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-register-ioctl-compat">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_register_ioctl_compat</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_register_ioctl_compat</refname>
 <refpurpose>
     register the device-specific 32bit compat control-ioctls
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_register_ioctl_compat </function></funcdef>
   <paramdef>snd_kctl_ioctl_func_t <parameter>fcn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fcn</parameter></term>
   <listitem>
    <para>
     ioctl callback function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-unregister-ioctl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_unregister_ioctl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_unregister_ioctl</refname>
 <refpurpose>
     de-register the device-specific control-ioctls
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_unregister_ioctl </function></funcdef>
   <paramdef>snd_kctl_ioctl_func_t <parameter>fcn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fcn</parameter></term>
   <listitem>
    <para>
     ioctl callback function to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-unregister-ioctl-compat">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_unregister_ioctl_compat</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_unregister_ioctl_compat</refname>
 <refpurpose>
     de-register the device-specific compat 32bit control-ioctls
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_unregister_ioctl_compat </function></funcdef>
   <paramdef>snd_kctl_ioctl_func_t <parameter>fcn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fcn</parameter></term>
   <listitem>
    <para>
     ioctl callback function to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-boolean-mono-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_boolean_mono_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_boolean_mono_info</refname>
 <refpurpose>
     Helper function for a standard boolean info callback with a mono channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_boolean_mono_info </function></funcdef>
   <paramdef>struct snd_kcontrol * <parameter>kcontrol</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_info * <parameter>uinfo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kcontrol</parameter></term>
   <listitem>
    <para>
     the kcontrol instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uinfo</parameter></term>
   <listitem>
    <para>
     info to store
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a function that can be used as info callback for a standard
   boolean control with a single mono channel.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-boolean-stereo-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_boolean_stereo_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_boolean_stereo_info</refname>
 <refpurpose>
     Helper function for a standard boolean info callback with stereo two channels
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_boolean_stereo_info </function></funcdef>
   <paramdef>struct snd_kcontrol * <parameter>kcontrol</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_info * <parameter>uinfo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kcontrol</parameter></term>
   <listitem>
    <para>
     the kcontrol instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uinfo</parameter></term>
   <listitem>
    <para>
     info to store
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a function that can be used as info callback for a standard
   boolean control with stereo two channels.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-enum-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_enum_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_enum_info</refname>
 <refpurpose>
     fills the info structure for an enumerated control
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_enum_info </function></funcdef>
   <paramdef>struct snd_ctl_elem_info * <parameter>info</parameter></paramdef>
   <paramdef>unsigned int <parameter>channels</parameter></paramdef>
   <paramdef>unsigned int <parameter>items</parameter></paramdef>
   <paramdef>const char *const <parameter>names[]</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     the structure to be filled
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>channels</parameter></term>
   <listitem>
    <para>
     the number of the control's channels; often one
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>items</parameter></term>
   <listitem>
    <para>
     the number of control values; also the size of <parameter>names</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>names[]</parameter></term>
   <listitem>
    <para>
     an array containing the names of all control values
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets all required fields in <parameter>info</parameter> to their appropriate values.
   If the control's accessibility is not the default (readable and writable),
   the caller has to fill <parameter>info</parameter>-&gt;access.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero.
</para>
</refsect1>
</refentry>

<!-- sound/core/pcm_lib.c -->
<refentry id="API-snd-pcm-set-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_set_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_set_ops</refname>
 <refpurpose>
  set the PCM operators
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_set_ops </function></funcdef>
   <paramdef>struct snd_pcm * <parameter>pcm</parameter></paramdef>
   <paramdef>int <parameter>direction</parameter></paramdef>
   <paramdef>const struct snd_pcm_ops * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     the pcm instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>direction</parameter></term>
   <listitem>
    <para>
     stream direction, SNDRV_PCM_STREAM_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     the operator table
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets the given PCM operators to the pcm instance.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-set-sync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_set_sync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_set_sync</refname>
 <refpurpose>
     set the PCM sync id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_set_sync </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets the PCM sync identifier for the card.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-interval-refine">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_interval_refine</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_interval_refine</refname>
 <refpurpose>
     refine the interval value of configurator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_interval_refine </function></funcdef>
   <paramdef>struct snd_interval * <parameter>i</parameter></paramdef>
   <paramdef>const struct snd_interval * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     the interval value to refine
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     the interval value to refer to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refines the interval value with the reference value.
   The interval is changed to the range satisfying both intervals.
   The interval status (min, max, integer, etc.) are evaluated.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Positive if the value is changed, zero if it's not changed, or a
   negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-interval-ratnum">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_interval_ratnum</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_interval_ratnum</refname>
 <refpurpose>
     refine the interval value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_interval_ratnum </function></funcdef>
   <paramdef>struct snd_interval * <parameter>i</parameter></paramdef>
   <paramdef>unsigned int <parameter>rats_count</parameter></paramdef>
   <paramdef>const struct snd_ratnum * <parameter>rats</parameter></paramdef>
   <paramdef>unsigned int * <parameter>nump</parameter></paramdef>
   <paramdef>unsigned int * <parameter>denp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     interval to refine
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rats_count</parameter></term>
   <listitem>
    <para>
     number of ratnum_t 
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rats</parameter></term>
   <listitem>
    <para>
     ratnum_t array
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nump</parameter></term>
   <listitem>
    <para>
     pointer to store the resultant numerator
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>denp</parameter></term>
   <listitem>
    <para>
     pointer to store the resultant denominator
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Positive if the value is changed, zero if it's not changed, or a
   negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-interval-list">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_interval_list</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_interval_list</refname>
 <refpurpose>
     refine the interval value from the list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_interval_list </function></funcdef>
   <paramdef>struct snd_interval * <parameter>i</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
   <paramdef>const unsigned int * <parameter>list</parameter></paramdef>
   <paramdef>unsigned int <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     the interval value to refine
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of elements in the list
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     the value list
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     the bit-mask to evaluate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refines the interval value from the list.
   When mask is non-zero, only the elements corresponding to bit 1 are
   evaluated.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Positive if the value is changed, zero if it's not changed, or a
   negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-interval-ranges">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_interval_ranges</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_interval_ranges</refname>
 <refpurpose>
     refine the interval value from the list of ranges
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_interval_ranges </function></funcdef>
   <paramdef>struct snd_interval * <parameter>i</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
   <paramdef>const struct snd_interval * <parameter>ranges</parameter></paramdef>
   <paramdef>unsigned int <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     the interval value to refine
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of elements in the list of ranges
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ranges</parameter></term>
   <listitem>
    <para>
     the ranges list
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     the bit-mask to evaluate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refines the interval value from the list of ranges.
   When mask is non-zero, only the elements corresponding to bit 1 are
   evaluated.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Positive if the value is changed, zero if it's not changed, or a
   negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-rule-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_rule_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_rule_add</refname>
 <refpurpose>
     add the hw-constraint rule
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_rule_add </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>int <parameter>var</parameter></paramdef>
   <paramdef>snd_pcm_hw_rule_func_t <parameter>func</parameter></paramdef>
   <paramdef>void * <parameter>private</parameter></paramdef>
   <paramdef>int <parameter>dep</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     the pcm runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     the variable to evaluate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>func</parameter></term>
   <listitem>
    <para>
     the evaluation function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>private</parameter></term>
   <listitem>
    <para>
     the private data pointer passed to function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dep</parameter></term>
   <listitem>
    <para>
     the dependent variables
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-mask64">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_mask64</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_mask64</refname>
 <refpurpose>
     apply the given bitmap mask constraint
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_mask64 </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>u_int64_t <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the mask
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     the 64bit bitmap mask
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Apply the constraint of the given bitmap mask to a 64-bit mask parameter.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-integer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_integer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_integer</refname>
 <refpurpose>
     apply an integer constraint to an interval
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_integer </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the integer constraint
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Apply the constraint of integer to an interval parameter.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Positive if the value is changed, zero if it's not changed, or a
   negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-minmax">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_minmax</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_minmax</refname>
 <refpurpose>
     apply a min/max range constraint to an interval
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_minmax </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>unsigned int <parameter>min</parameter></paramdef>
   <paramdef>unsigned int <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the range
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     the minimal value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     the maximal value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Apply the min/max range constraint to an interval parameter.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Positive if the value is changed, zero if it's not changed, or a
   negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-list">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_list</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_list</refname>
 <refpurpose>
     apply a list of constraints to a parameter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_list </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>const struct snd_pcm_hw_constraint_list * <parameter>l</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the list constraint
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>l</parameter></term>
   <listitem>
    <para>
     list
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Apply the list of constraints to an interval parameter.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-ranges">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_ranges</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_ranges</refname>
 <refpurpose>
     apply list of range constraints to a parameter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_ranges </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>const struct snd_pcm_hw_constraint_ranges * <parameter>r</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the list of range constraints
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     ranges
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Apply the list of range constraints to an interval parameter.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-ratnums">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_ratnums</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_ratnums</refname>
 <refpurpose>
     apply ratnums constraint to a parameter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_ratnums </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>const struct snd_pcm_hw_constraint_ratnums * <parameter>r</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the ratnums constraint
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     struct snd_ratnums constriants
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-ratdens">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_ratdens</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_ratdens</refname>
 <refpurpose>
     apply ratdens constraint to a parameter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_ratdens </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>const struct snd_pcm_hw_constraint_ratdens * <parameter>r</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the ratdens constraint
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     struct snd_ratdens constriants
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-msbits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_msbits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_msbits</refname>
 <refpurpose>
     add a hw constraint msbits rule
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_msbits </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>unsigned int <parameter>width</parameter></paramdef>
   <paramdef>unsigned int <parameter>msbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>width</parameter></term>
   <listitem>
    <para>
     sample bits width
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msbits</parameter></term>
   <listitem>
    <para>
     msbits width
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This constraint will set the number of most significant bits (msbits) if a
   sample format with the specified width has been select. If width is set to 0
   the msbits will be set for any sample format with a width larger than the
   specified msbits.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-step">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_step</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_step</refname>
 <refpurpose>
     add a hw constraint step rule
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_step </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>unsigned long <parameter>step</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the step constraint
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>step</parameter></term>
   <listitem>
    <para>
     step size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-pow2">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_pow2</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_pow2</refname>
 <refpurpose>
     add a hw constraint power-of-2 rule
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_pow2 </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the power-of-2 constraint
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-rule-noresample">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_rule_noresample</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_rule_noresample</refname>
 <refpurpose>
     add a rule to allow disabling hw resampling
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_rule_noresample </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>base_rate</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>base_rate</parameter></term>
   <listitem>
    <para>
     the rate at which the hardware does not resample
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-param-value">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_param_value</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_param_value</refname>
 <refpurpose>
     return <parameter>params</parameter> field <parameter>var</parameter> value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_param_value </function></funcdef>
   <paramdef>const struct snd_pcm_hw_params * <parameter>params</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>int * <parameter>dir</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     the hw_params instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     parameter to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dir</parameter></term>
   <listitem>
    <para>
     pointer to the direction (-1,0,1) or <constant>NULL</constant>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The value for field <parameter>var</parameter> if it's fixed in configuration space
   defined by <parameter>params</parameter>. -<constant>EINVAL</constant> otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-param-first">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_param_first</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_param_first</refname>
 <refpurpose>
     refine config space and return minimum value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_param_first </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>pcm</parameter></paramdef>
   <paramdef>struct snd_pcm_hw_params * <parameter>params</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>int * <parameter>dir</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     PCM instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     the hw_params instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     parameter to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dir</parameter></term>
   <listitem>
    <para>
     pointer to the direction (-1,0,1) or <constant>NULL</constant>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Inside configuration space defined by <parameter>params</parameter> remove from <parameter>var</parameter> all
   values &gt; minimum. Reduce configuration space accordingly.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The minimum, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-param-last">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_param_last</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_param_last</refname>
 <refpurpose>
     refine config space and return maximum value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_param_last </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>pcm</parameter></paramdef>
   <paramdef>struct snd_pcm_hw_params * <parameter>params</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>int * <parameter>dir</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     PCM instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     the hw_params instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     parameter to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dir</parameter></term>
   <listitem>
    <para>
     pointer to the direction (-1,0,1) or <constant>NULL</constant>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Inside configuration space defined by <parameter>params</parameter> remove from <parameter>var</parameter> all
   values &lt; maximum. Reduce configuration space accordingly.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The maximum, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-ioctl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_ioctl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_ioctl</refname>
 <refpurpose>
     a generic PCM ioctl callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_ioctl </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned int <parameter>cmd</parameter></paramdef>
   <paramdef>void * <parameter>arg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     ioctl command
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>arg</parameter></term>
   <listitem>
    <para>
     ioctl argument
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Processes the generic ioctl commands for PCM.
   Can be passed as the ioctl callback for PCM ops.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-period-elapsed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_period_elapsed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_period_elapsed</refname>
 <refpurpose>
     update the pcm status for the next period
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_period_elapsed </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is called from the interrupt handler when the
   PCM has processed the period size.  It will update the current
   pointer, wake up sleepers, etc.
   </para><para>

   Even if more than one periods have elapsed since the last call, you
   have to call this only once.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-add-chmap-ctls">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_add_chmap_ctls</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_add_chmap_ctls</refname>
 <refpurpose>
     create channel-mapping control elements
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_add_chmap_ctls </function></funcdef>
   <paramdef>struct snd_pcm * <parameter>pcm</parameter></paramdef>
   <paramdef>int <parameter>stream</parameter></paramdef>
   <paramdef>const struct snd_pcm_chmap_elem * <parameter>chmap</parameter></paramdef>
   <paramdef>int <parameter>max_channels</parameter></paramdef>
   <paramdef>unsigned long <parameter>private_value</parameter></paramdef>
   <paramdef>struct snd_pcm_chmap ** <parameter>info_ret</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     the assigned PCM instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>stream</parameter></term>
   <listitem>
    <para>
     stream direction
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>chmap</parameter></term>
   <listitem>
    <para>
     channel map elements (for query)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_channels</parameter></term>
   <listitem>
    <para>
     the max number of channels for the stream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>private_value</parameter></term>
   <listitem>
    <para>
     the value passed to each kcontrol's private_value field
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info_ret</parameter></term>
   <listitem>
    <para>
     store struct snd_pcm_chmap instance if non-NULL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Create channel-mapping control elements assigned to the given PCM stream(s).
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error value.
</para>
</refsect1>
</refentry>

<!-- sound/core/hwdep.c -->
<refentry id="API-snd-hwdep-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_hwdep_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_hwdep_new</refname>
 <refpurpose>
  create a new hwdep instance
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_hwdep_new </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>char * <parameter>id</parameter></paramdef>
   <paramdef>int <parameter>device</parameter></paramdef>
   <paramdef>struct snd_hwdep ** <parameter>rhwdep</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the id string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device index (zero-based)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rhwdep</parameter></term>
   <listitem>
    <para>
     the pointer to store the new hwdep instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new hwdep instance with the given index on the card.
   The callbacks (hwdep-&gt;ops) must be set on the returned instance
   after this call manually by the caller.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<!-- sound/core/pcm_native.c -->
<refentry id="API-snd-pcm-stream-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_stream_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_stream_lock</refname>
 <refpurpose>
  Lock the PCM stream
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_stream_lock </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This locks the PCM stream's spinlock or mutex depending on the nonatomic
   flag of the given substream.  This also takes the global link rw lock
   (or rw sem), too, for avoiding the race with linked streams.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-stream-unlock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_stream_unlock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_stream_unlock</refname>
 <refpurpose>
     Unlock the PCM stream
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_stream_unlock </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This unlocks the PCM stream that has been locked via <function><link linkend="API-snd-pcm-stream-lock">snd_pcm_stream_lock</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-stream-lock-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_stream_lock_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_stream_lock_irq</refname>
 <refpurpose>
     Lock the PCM stream
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_stream_lock_irq </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This locks the PCM stream like <function><link linkend="API-snd-pcm-stream-lock">snd_pcm_stream_lock</link></function> and disables the local
   IRQ (only when nonatomic is false).  In nonatomic case, this is identical
   as <function><link linkend="API-snd-pcm-stream-lock">snd_pcm_stream_lock</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-stream-unlock-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_stream_unlock_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_stream_unlock_irq</refname>
 <refpurpose>
     Unlock the PCM stream
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_stream_unlock_irq </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a counter-part of <function><link linkend="API-snd-pcm-stream-lock-irq">snd_pcm_stream_lock_irq</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-stream-unlock-irqrestore">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_stream_unlock_irqrestore</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_stream_unlock_irqrestore</refname>
 <refpurpose>
     Unlock the PCM stream
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_stream_unlock_irqrestore </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned long <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     irq flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a counter-part of <function><link linkend="API-snd-pcm-stream-lock-irqsave">snd_pcm_stream_lock_irqsave</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-stop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_stop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_stop</refname>
 <refpurpose>
     try to stop all running streams in the substream group
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_stop </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>snd_pcm_state_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the PCM substream instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     PCM state after stopping the stream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The state of each stream is then changed to the given state unconditionally.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-stop-xrun">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_stop_xrun</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_stop_xrun</refname>
 <refpurpose>
     stop the running streams as XRUN
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_stop_xrun </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the PCM substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This stops the given running substream (and all linked substreams) as XRUN.
   Unlike <function><link linkend="API-snd-pcm-stop">snd_pcm_stop</link></function>, this function takes the substream lock by itself.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful, or a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_suspend</refname>
 <refpurpose>
     trigger SUSPEND to all linked streams
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_suspend </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the PCM substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   After this call, all streams are changed to SUSPENDED state.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful (or <parameter>substream</parameter> is <constant>NULL</constant>), or a negative error
   code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-suspend-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_suspend_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_suspend_all</refname>
 <refpurpose>
     trigger SUSPEND to all substreams in the given pcm
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_suspend_all </function></funcdef>
   <paramdef>struct snd_pcm * <parameter>pcm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     the PCM instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   After this call, all streams are changed to SUSPENDED state.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if successful (or <parameter>pcm</parameter> is <constant>NULL</constant>), or a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-default-mmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_default_mmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_default_mmap</refname>
 <refpurpose>
     Default PCM data mmap function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_default_mmap </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>area</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>area</parameter></term>
   <listitem>
    <para>
     VMA
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the default mmap handler for PCM data.  When mmap pcm_ops is NULL,
   this function is invoked implicitly.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-mmap-iomem">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_mmap_iomem</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_mmap_iomem</refname>
 <refpurpose>
     Default PCM data mmap function for I/O mem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_mmap_iomem </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>area</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     PCM substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>area</parameter></term>
   <listitem>
    <para>
     VMA
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When your hardware uses the iomapped pages as the hardware buffer and
   wants to mmap it, pass this function as mmap pcm_ops.  Note that this
   is supposed to work only on limited architectures.
</para>
</refsect1>
</refentry>

<!-- sound/core/memalloc.c -->
<refentry id="API-snd-malloc-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_malloc_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_malloc_pages</refname>
 <refpurpose>
  allocate pages with the given size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>snd_malloc_pages </function></funcdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the size to allocate in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_flags</parameter></term>
   <listitem>
    <para>
     the allocation conditions, GFP_XXX
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates the physically contiguous pages with the given size.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The pointer of the buffer, or <constant>NULL</constant> if no enough memory.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-free-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_free_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_free_pages</refname>
 <refpurpose>
     release the pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_free_pages </function></funcdef>
   <paramdef>void * <parameter>ptr</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     the buffer pointer to release
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the allocated buffer size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases the buffer allocated via <function><link linkend="API-snd-malloc-pages">snd_malloc_pages</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-alloc-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_alloc_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_alloc_pages</refname>
 <refpurpose>
     allocate the buffer area according to the given type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_dma_alloc_pages </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>device</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>struct snd_dma_buffer * <parameter>dmab</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the DMA buffer type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the buffer size to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dmab</parameter></term>
   <listitem>
    <para>
     buffer allocation record to store the allocated data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls the memory-allocator function for the corresponding
   buffer type.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if the buffer with the given size is allocated successfully,
   otherwise a negative value on error.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-alloc-pages-fallback">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_alloc_pages_fallback</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_alloc_pages_fallback</refname>
 <refpurpose>
     allocate the buffer area according to the given type with fallback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_dma_alloc_pages_fallback </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>device</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>struct snd_dma_buffer * <parameter>dmab</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the DMA buffer type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the buffer size to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dmab</parameter></term>
   <listitem>
    <para>
     buffer allocation record to store the allocated data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls the memory-allocator function for the corresponding
   buffer type.  When no space is left, this function reduces the size and
   tries to allocate again.  The size actually allocated is stored in
   res_size argument.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Zero if the buffer with the given size is allocated successfully,
   otherwise a negative value on error.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-free-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_free_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_free_pages</refname>
 <refpurpose>
     release the allocated buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_dma_free_pages </function></funcdef>
   <paramdef>struct snd_dma_buffer * <parameter>dmab</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmab</parameter></term>
   <listitem>
    <para>
     the buffer allocation record to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases the allocated buffer via <function><link linkend="API-snd-dma-alloc-pages">snd_dma_alloc_pages</link></function>.
</para>
</refsect1>
</refentry>

<!-- FIXME: Removed for now since no structured comments in source
X!Isound/sound_firmware.c
-->
  </chapter>

  <chapter id="mediadev">
     <title>Media Devices</title>

     <sect1><title>Video2Linux devices</title>
<!-- include/media/tuner.h -->
<refentry id="API-enum-tuner-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum tuner_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum tuner_mode</refname>
 <refpurpose>
  Mode of the tuner
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum tuner_mode {
  T_RADIO,
  T_ANALOG_TV
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>T_RADIO</term>
      <listitem><para>
Tuner core will work in radio mode
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>T_ANALOG_TV</term>
      <listitem><para>
Tuner core will work in analog TV mode
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Older boards only had a single tuner device, but some devices have a
   separate tuner for radio. In any case, the tuner-core needs to know if
   the tuner chip(s) will be used in radio mode or analog TV mode, as, on
   radio mode, frequencies are specified on a different range than on TV
   mode. This enum is used by the tuner core in order to work with the
   proper tuner range and eventually use a different tuner chip while in
   radio mode.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-tuner-setup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct tuner_setup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct tuner_setup</refname>
 <refpurpose>
     setup the tuner chipsets
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct tuner_setup {
  unsigned short addr;
  unsigned int type;
  unsigned int mode_mask;
  void * config;
  int (* tuner_callback) (void *dev, int component, int cmd, int arg);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>addr</term>
      <listitem><para>
   I2C address used to control the tuner device/chipset
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type</term>
      <listitem><para>
   Type of the tuner, as defined at the TUNER_* macros.
   Each different tuner model should have an unique
   identifier.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_mask</term>
      <listitem><para>
   Mask with the allowed tuner modes: V4L2_TUNER_RADIO,
   V4L2_TUNER_ANALOG_TV and/or V4L2_TUNER_DIGITAL_TV,
   describing if the tuner should be used to support
   Radio, analog TV and/or digital TV.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>config</term>
      <listitem><para>
   Used to send tuner-specific configuration for complex
   tuners that require extra parameters to be set.
   Only a very few tuners require it and its usage on
   newer tuners should be avoided.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tuner_callback</term>
      <listitem><para>
   Some tuners require to call back the bridge driver,
   in order to do some tasks like rising a GPIO at the
   bridge chipset, in order to do things like resetting
   the device.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Older boards only had a single tuner device. Nowadays multiple tuner
   devices may be present on a single board. Using TUNER_SET_TYPE_ADDR
   to pass the tuner_setup structure it is possible to setup each tuner
   device in turn.
   </para><para>

   Since multiple devices may be present it is no longer sufficient to
   send a command to a single i2c device. Instead you should broadcast
   the command to all i2c devices.
   </para><para>

   By setting the mode_mask correctly you can select which commands are
   accepted by a specific tuner device. For example, set mode_mask to
   T_RADIO if the device is a radio-only tuner. That specific tuner will
   only accept commands when the tuner is in radio mode and ignore them
   when the tuner is set to TV mode.
</para>
</refsect1>
</refentry>

<!-- include/media/tuner-types.h -->
<refentry id="API-enum-param-type">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum param_type</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum param_type</refname>
 <refpurpose>
  type of the tuner pameters
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum param_type {
  TUNER_PARAM_TYPE_RADIO,
  TUNER_PARAM_TYPE_PAL,
  TUNER_PARAM_TYPE_SECAM,
  TUNER_PARAM_TYPE_NTSC,
  TUNER_PARAM_TYPE_DIGITAL
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>TUNER_PARAM_TYPE_RADIO</term>
      <listitem><para>
Tuner params are for FM and/or AM radio
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>TUNER_PARAM_TYPE_PAL</term>
      <listitem><para>
Tuner params are for PAL color TV standard
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>TUNER_PARAM_TYPE_SECAM</term>
      <listitem><para>
Tuner params are for SECAM color TV standard
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>TUNER_PARAM_TYPE_NTSC</term>
      <listitem><para>
Tuner params are for NTSC color TV standard
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>TUNER_PARAM_TYPE_DIGITAL</term>
      <listitem><para>
Tuner params are for digital TV
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-struct-tuner-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct tuner_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct tuner_range</refname>
 <refpurpose>
     define the frequencies supported by the tuner
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct tuner_range {
  unsigned short limit;
  unsigned char config;
  unsigned char cb;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>limit</term>
      <listitem><para>
   Max frequency supported by that range, in 62.5 kHz
   (TV) or 62.5 Hz (Radio), as defined by
   V4L2_TUNER_CAP_LOW.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>config</term>
      <listitem><para>
   Value of the band switch byte (BB) to setup this mode.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cb</term>
      <listitem><para>
   Value of the CB byte to setup this mode.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Please notice that digital tuners like xc3028/xc4000/xc5000 don't use
   those ranges, as they're defined inside the driver. This is used by
   analog tuners that are compatible with the <quote>Philips way</quote> to setup the
   tuners. On those devices, the tuner set is done via 4 bytes:
   divider byte1 (DB1), divider byte 2 (DB2), Control byte (CB) and
   band switch byte (BB).
   Some tuners also have an additional optional Auxiliary byte (AB).
</para>
</refsect1>
</refentry>

<refentry id="API-struct-tuner-params">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct tuner_params</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct tuner_params</refname>
 <refpurpose>
     Parameters to be used to setup the tuner. Those are used by drivers/media/tuners/tuner-types.c in order to specify the tuner properties. Most of the parameters are for tuners based on tda9887 IF-PLL multi-standard analog TV/Radio demodulator, with is very common on legacy analog tuners.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct tuner_params {
  enum param_type type;
  unsigned int cb_first_if_lower_freq:1;
  unsigned int has_tda9887:1;
  unsigned int port1_fm_high_sensitivity:1;
  unsigned int port2_fm_high_sensitivity:1;
  unsigned int fm_gain_normal:1;
  unsigned int intercarrier_mode:1;
  unsigned int port1_active:1;
  unsigned int port2_active:1;
  unsigned int port1_invert_for_secam_lc:1;
  unsigned int port2_invert_for_secam_lc:1;
  unsigned int port1_set_for_fm_mono:1;
  unsigned int default_pll_gating_18:1;
  unsigned int radio_if:2;
  signed int default_top_low:5;
  signed int default_top_mid:5;
  signed int default_top_high:5;
  signed int default_top_secam_low:5;
  signed int default_top_secam_mid:5;
  signed int default_top_secam_high:5;
  u16 iffreq;
  unsigned int count;
  struct tuner_range * ranges;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>type</term>
      <listitem><para>
   Type of the tuner parameters, as defined at
   enum param_type. If the tuner supports multiple
   standards, an array should be used, with one
   row per different standard.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cb_first_if_lower_freq</term>
      <listitem><para>
   Many Philips-based tuners have a comment in
   their datasheet like
   <quote>For channel selection involving band
   switching, and to ensure smooth tuning to the
   desired channel without causing unnecessary
   charge pump action, it is recommended to
   consider the difference between wanted channel
   frequency and the current channel frequency.
   Unnecessary charge pump action will result
   in very low tuning voltage which may drive the
   oscillator to extreme conditions</quote>.
   Set cb_first_if_lower_freq to 1, if this check
   is required for this tuner. I tested this for
   PAL by first setting the TV frequency to
   203 MHz and then switching to 96.6 MHz FM
   radio. The result was static unless the
   control byte was sent first.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>has_tda9887</term>
      <listitem><para>
   Set to 1 if this tuner uses a tda9887
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port1_fm_high_sensitivity</term>
      <listitem><para>
   Many Philips tuners use tda9887 PORT1 to select
   the FM radio sensitivity. If this setting is 1,
   then set PORT1 to 1 to get proper FM reception.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port2_fm_high_sensitivity</term>
      <listitem><para>
   Some Philips tuners use tda9887 PORT2 to select
   the FM radio sensitivity. If this setting is 1,
   then set PORT2 to 1 to get proper FM reception.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fm_gain_normal</term>
      <listitem><para>
   Some Philips tuners use tda9887 cGainNormal to
   select the FM radio sensitivity. If this
   setting is 1, e register will use cGainNormal
   instead of cGainLow.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>intercarrier_mode</term>
      <listitem><para>
   Most tuners with a tda9887 use QSS mode.
   Some (cheaper) tuners use Intercarrier mode.
   If this setting is 1, then the tuner needs to
   be set to intercarrier mode.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port1_active</term>
      <listitem><para>
   This setting sets the default value for PORT1.
   0 means inactive, 1 means active. Note: the
   actual bit value written to the tda9887 is
   inverted. So a 0 here means a 1 in the B6 bit.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port2_active</term>
      <listitem><para>
   This setting sets the default value for PORT2.
   0 means inactive, 1 means active. Note: the
   actual bit value written to the tda9887 is
   inverted. So a 0 here means a 1 in the B7 bit.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port1_invert_for_secam_lc</term>
      <listitem><para>
   Sometimes PORT1 is inverted when the SECAM-L'
   standard is selected. Set this bit to 1 if this
   is needed.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port2_invert_for_secam_lc</term>
      <listitem><para>
   Sometimes PORT2 is inverted when the SECAM-L'
   standard is selected. Set this bit to 1 if this
   is needed.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port1_set_for_fm_mono</term>
      <listitem><para>
   Some cards require PORT1 to be 1 for mono Radio
   FM and 0 for stereo.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>default_pll_gating_18</term>
      <listitem><para>
   Select 18% (or according to datasheet 0%)
   L standard PLL gating, vs the driver default
   of 36%.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>radio_if</term>
      <listitem><para>
   IF to use in radio mode.  Tuners with a
   separate radio IF filter seem to use 10.7,
   while those without use 33.3 for PAL/SECAM
   tuners and 41.3 for NTSC tuners.
   0 = 10.7, 1 = 33.3, 2 = 41.3
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>default_top_low</term>
      <listitem><para>
   Default tda9887 TOP value in dB for the low
   band. Default is 0. Range: -16:+15
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>default_top_mid</term>
      <listitem><para>
   Default tda9887 TOP value in dB for the mid
   band. Default is 0. Range: -16:+15
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>default_top_high</term>
      <listitem><para>
   Default tda9887 TOP value in dB for the high
   band. Default is 0. Range: -16:+15
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>default_top_secam_low</term>
      <listitem><para>
   Default tda9887 TOP value in dB for SECAM-L/L'
   for the low band. Default is 0. Several tuners
   require a different TOP value for the
   SECAM-L/L' standards. Range: -16:+15
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>default_top_secam_mid</term>
      <listitem><para>
   Default tda9887 TOP value in dB for SECAM-L/L'
   for the mid band. Default is 0. Several tuners
   require a different TOP value for the
   SECAM-L/L' standards. Range: -16:+15
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>default_top_secam_high</term>
      <listitem><para>
   Default tda9887 TOP value in dB for SECAM-L/L'
   for the high band. Default is 0. Several tuners
   require a different TOP value for the
   SECAM-L/L' standards. Range: -16:+15
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>iffreq</term>
      <listitem><para>
   Intermediate frequency (IF) used by the tuner
   on digital mode.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>count</term>
      <listitem><para>
   Size of the ranges array.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ranges</term>
      <listitem><para>
   Array with the frequency ranges supported by
   the tuner.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- include/media/tveeprom.h -->
<refentry id="API-enum-tveeprom-audio-processor">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum tveeprom_audio_processor</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum tveeprom_audio_processor</refname>
 <refpurpose>
  Specifies the type of audio processor used on a Hauppauge device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum tveeprom_audio_processor {
  TVEEPROM_AUDPROC_NONE,
  TVEEPROM_AUDPROC_INTERNAL,
  TVEEPROM_AUDPROC_MSP,
  TVEEPROM_AUDPROC_OTHER
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>TVEEPROM_AUDPROC_NONE</term>
      <listitem><para>
No audio processor present
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>TVEEPROM_AUDPROC_INTERNAL</term>
      <listitem><para>
The audio processor is internal to the
video processor
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>TVEEPROM_AUDPROC_MSP</term>
      <listitem><para>
The audio processor is a MSPXXXX device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>TVEEPROM_AUDPROC_OTHER</term>
      <listitem><para>
The audio processor is another device
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-struct-tveeprom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct tveeprom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct tveeprom</refname>
 <refpurpose>
     Contains the fields parsed from Hauppauge eeproms
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct tveeprom {
  u32 has_radio;
  u32 has_ir;
  u32 has_MAC_address;
  u32 tuner_type;
  u32 tuner_formats;
  u32 tuner_hauppauge_model;
  u32 tuner2_type;
  u32 tuner2_formats;
  u32 tuner2_hauppauge_model;
  u32 audio_processor;
  u32 decoder_processor;
  u32 model;
  u32 revision;
  u32 serial_number;
  char rev_str[5];
  u8 MAC_address[ETH_ALEN];
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>has_radio</term>
      <listitem><para>
   1 if the device has radio; 0 otherwise.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>has_ir</term>
      <listitem><para>
   If has_ir == 0, then it is unknown what the IR
   capabilities are. Otherwise:
   bit 0) 1 (= IR capabilities are known);
   bit 1) IR receiver present;
   bit 2) IR transmitter (blaster) present.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>has_MAC_address</term>
      <listitem><para>
   0: no MAC, 1: MAC present, 2: unknown.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tuner_type</term>
      <listitem><para>
   type of the tuner (TUNER_*, as defined at
   include/media/tuner.h).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tuner_formats</term>
      <listitem><para>
   Supported analog TV standards (V4L2_STD_*).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tuner_hauppauge_model</term>
      <listitem><para>
   Hauppauge's code for the device model number.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tuner2_type</term>
      <listitem><para>
   type of the second tuner (TUNER_*, as defined
   at include/media/tuner.h).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tuner2_formats</term>
      <listitem><para>
   Tuner 2 supported analog TV standards
   (V4L2_STD_*).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tuner2_hauppauge_model</term>
      <listitem><para>
   tuner 2 Hauppauge's code for the device model
   number.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>audio_processor</term>
      <listitem><para>
   analog audio decoder, as defined by enum
   tveeprom_audio_processor.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>decoder_processor</term>
      <listitem><para>
   Hauppauge's code for the decoder chipset.
   Unused by the drivers, as they probe the
   decoder based on the PCI or USB ID.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>model</term>
      <listitem><para>
   Hauppauge's model number
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>revision</term>
      <listitem><para>
   Card revision number
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>serial_number</term>
      <listitem><para>
   Card's serial number
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rev_str[5]</term>
      <listitem><para>
   Card revision converted to number
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>MAC_address[ETH_ALEN]</term>
      <listitem><para>
   MAC address for the network interface
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-tveeprom-hauppauge-analog">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>tveeprom_hauppauge_analog</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>tveeprom_hauppauge_analog</refname>
 <refpurpose>
     Fill struct tveeprom using the contents of the eeprom previously filled at <parameter>eeprom_data</parameter> field.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>tveeprom_hauppauge_analog </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">struct i2c_client</link> * <parameter>c</parameter></paramdef>
   <paramdef><link linkend="API-struct-tveeprom">struct tveeprom</link> * <parameter>tvee</parameter></paramdef>
   <paramdef>unsigned char * <parameter>eeprom_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2C client struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tvee</parameter></term>
   <listitem>
    <para>
     Struct to where the eeprom parsed data will be filled;
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>eeprom_data</parameter></term>
   <listitem>
    <para>
     Array with the contents of the eeprom_data. It should
     contain 256 bytes filled with the contents of the
     eeprom read from the Hauppauge device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-tveeprom-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>tveeprom_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>tveeprom_read</refname>
 <refpurpose>
     Reads the contents of the eeprom found at the Hauppauge devices.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>tveeprom_read </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">struct i2c_client</link> * <parameter>c</parameter></paramdef>
   <paramdef>unsigned char * <parameter>eedata</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2C client struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>eedata</parameter></term>
   <listitem>
    <para>
     Array where the eeprom content will be stored.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     Size of <parameter>eedata</parameter> array. If the eeprom content will be latter
     be parsed by <function><link linkend="API-tveeprom-hauppauge-analog">tveeprom_hauppauge_analog</link></function>, len should be, at
     least, 256.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- include/media/v4l2-async.h -->
<refentry id="API-struct-v4l2-async-subdev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_async_subdev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_async_subdev</refname>
 <refpurpose>
  sub-device descriptor, as known to a bridge
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_async_subdev {
  enum v4l2_async_match_type match_type;
  union match;
  struct list_head list;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>match_type</term>
      <listitem><para>
type of match that will be used
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>match</term>
      <listitem><para>
union of per-bus type matching data sets
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>list</term>
      <listitem><para>
used to link struct v4l2_async_subdev objects, waiting to be
probed, to a notifier-&gt;waiting list
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-async-notifier">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_async_notifier</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_async_notifier</refname>
 <refpurpose>
     v4l2_device notifier data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_async_notifier {
  unsigned int num_subdevs;
  struct v4l2_async_subdev ** subdevs;
  struct v4l2_device * v4l2_dev;
  struct list_head waiting;
  struct list_head done;
  struct list_head list;
  int (* bound) (struct v4l2_async_notifier *notifier,struct v4l2_subdev *subdev,struct v4l2_async_subdev *asd);
  int (* complete) (struct v4l2_async_notifier *notifier);
  void (* unbind) (struct v4l2_async_notifier *notifier,struct v4l2_subdev *subdev,struct v4l2_async_subdev *asd);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>num_subdevs</term>
      <listitem><para>
   number of subdevices
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>subdevs</term>
      <listitem><para>
   array of pointers to subdevice descriptors
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>v4l2_dev</term>
      <listitem><para>
   pointer to struct v4l2_device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>waiting</term>
      <listitem><para>
   list of struct v4l2_async_subdev, waiting for their drivers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>done</term>
      <listitem><para>
   list of struct v4l2_subdev, already probed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>list</term>
      <listitem><para>
   member in a global list of notifiers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bound</term>
      <listitem><para>
   a subdevice driver has successfully probed one of subdevices
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>complete</term>
      <listitem><para>
   all subdevices have been probed successfully
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>unbind</term>
      <listitem><para>
   a subdevice is leaving
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- include/media/v4l2-ctrls.h -->
<refentry id="API-struct-v4l2-ctrl-ptr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>union v4l2_ctrl_ptr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>union v4l2_ctrl_ptr</refname>
 <refpurpose>
  A pointer to a control value.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
union v4l2_ctrl_ptr {
  s32 * p_s32;
  s64 * p_s64;
  u8 * p_u8;
  u16 * p_u16;
  u32 * p_u32;
  char * p_char;
  void * p;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>p_s32</term>
      <listitem><para>
Pointer to a 32-bit signed value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p_s64</term>
      <listitem><para>
Pointer to a 64-bit signed value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p_u8</term>
      <listitem><para>
Pointer to a 8-bit unsigned value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p_u16</term>
      <listitem><para>
Pointer to a 16-bit unsigned value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p_u32</term>
      <listitem><para>
Pointer to a 32-bit unsigned value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p_char</term>
      <listitem><para>
Pointer to a string.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p</term>
      <listitem><para>
Pointer to a compound value.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-ctrl-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_ctrl_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_ctrl_ops</refname>
 <refpurpose>
     The control operations that the driver has to provide.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_ctrl_ops {
  int (* g_volatile_ctrl) (struct v4l2_ctrl *ctrl);
  int (* try_ctrl) (struct v4l2_ctrl *ctrl);
  int (* s_ctrl) (struct v4l2_ctrl *ctrl);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>g_volatile_ctrl</term>
      <listitem><para>
   Get a new value for this control. Generally only relevant
   for volatile (and usually read-only) controls such as a control
   that returns the current signal strength which changes
   continuously.
   If not set, then the currently cached value will be returned.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>try_ctrl</term>
      <listitem><para>
   Test whether the control's value is valid. Only relevant when
   the usual min/max/step checks are not sufficient.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_ctrl</term>
      <listitem><para>
   Actually set the new control value. s_ctrl is compulsory. The
   ctrl-&gt;handler-&gt;lock is held when these ops are called, so no
   one else can access controls owned by that handler.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-ctrl-type-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_ctrl_type_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_ctrl_type_ops</refname>
 <refpurpose>
     The control type operations that the driver has to provide.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_ctrl_type_ops {
  bool (* equal) (const struct v4l2_ctrl *ctrl, u32 idx,union v4l2_ctrl_ptr ptr1,union v4l2_ctrl_ptr ptr2);
  void (* init) (const struct v4l2_ctrl *ctrl, u32 idx,union v4l2_ctrl_ptr ptr);
  void (* log) (const struct v4l2_ctrl *ctrl);
  int (* validate) (const struct v4l2_ctrl *ctrl, u32 idx,union v4l2_ctrl_ptr ptr);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>equal</term>
      <listitem><para>
   return true if both values are equal.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>init</term>
      <listitem><para>
   initialize the value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>log</term>
      <listitem><para>
   log the value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>validate</term>
      <listitem><para>
   validate the value. Return 0 on success and a negative value otherwise.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-ctrl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_ctrl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_ctrl</refname>
 <refpurpose>
     The control structure.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_ctrl {
  struct list_head node;
  struct list_head ev_subs;
  struct v4l2_ctrl_handler * handler;
  struct v4l2_ctrl ** cluster;
  unsigned ncontrols;
  unsigned int done:1;
  unsigned int is_new:1;
  unsigned int has_changed:1;
  unsigned int is_private:1;
  unsigned int is_auto:1;
  unsigned int is_int:1;
  unsigned int is_string:1;
  unsigned int is_ptr:1;
  unsigned int is_array:1;
  unsigned int has_volatiles:1;
  unsigned int call_notify:1;
  unsigned int manual_mode_value:8;
  const struct v4l2_ctrl_ops * ops;
  const struct v4l2_ctrl_type_ops * type_ops;
  u32 id;
  const char * name;
  enum v4l2_ctrl_type type;
  s64 minimum;
  s64 maximum;
  s64 default_value;
  u32 elems;
  u32 elem_size;
  u32 dims[V4L2_CTRL_MAX_DIMS];
  u32 nr_of_dims;
  union cur;
  union v4l2_ctrl_ptr p_new;
  union v4l2_ctrl_ptr p_cur;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>node</term>
      <listitem><para>
   The list node.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ev_subs</term>
      <listitem><para>
   The list of control event subscriptions.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>handler</term>
      <listitem><para>
   The handler that owns the control.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cluster</term>
      <listitem><para>
   Point to start of cluster array.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ncontrols</term>
      <listitem><para>
   Number of controls in cluster array.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>done</term>
      <listitem><para>
   Internal flag: set for each processed control.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>is_new</term>
      <listitem><para>
   Set when the user specified a new value for this control. It
   is also set when called from v4l2_ctrl_handler_setup. Drivers
   should never set this flag.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>has_changed</term>
      <listitem><para>
   Set when the current value differs from the new value. Drivers
   should never use this flag.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>is_private</term>
      <listitem><para>
   If set, then this control is private to its handler and it
   will not be added to any other handlers. Drivers can set
   this flag.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>is_auto</term>
      <listitem><para>
   If set, then this control selects whether the other cluster
   members are in 'automatic' mode or 'manual' mode. This is
   used for autogain/gain type clusters. Drivers should never
   set this flag directly.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>is_int</term>
      <listitem><para>
   If set, then this control has a simple integer value (i.e. it
   uses ctrl-&gt;val).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>is_string</term>
      <listitem><para>
   If set, then this control has type V4L2_CTRL_TYPE_STRING.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>is_ptr</term>
      <listitem><para>
   If set, then this control is an array and/or has type &gt;= V4L2_CTRL_COMPOUND_TYPES
   and/or has type V4L2_CTRL_TYPE_STRING. In other words, struct
   v4l2_ext_control uses field p to point to the data.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>is_array</term>
      <listitem><para>
   If set, then this control contains an N-dimensional array.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>has_volatiles</term>
      <listitem><para>
   If set, then one or more members of the cluster are volatile.
   Drivers should never touch this flag.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>call_notify</term>
      <listitem><para>
   If set, then call the handler's notify function whenever the
   control's value changes.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>manual_mode_value</term>
      <listitem><para>
   If the is_auto flag is set, then this is the value
   of the auto control that determines if that control is in
   manual mode. So if the value of the auto control equals this
   value, then the whole cluster is in manual mode. Drivers should
   never set this flag directly.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ops</term>
      <listitem><para>
   The control ops.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type_ops</term>
      <listitem><para>
   The control type ops.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id</term>
      <listitem><para>
   The control ID.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name</term>
      <listitem><para>
   The control name.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type</term>
      <listitem><para>
   The control type.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>minimum</term>
      <listitem><para>
   The control's minimum value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>maximum</term>
      <listitem><para>
   The control's maximum value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>default_value</term>
      <listitem><para>
   The control's default value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>elems</term>
      <listitem><para>
   The number of elements in the N-dimensional array.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>elem_size</term>
      <listitem><para>
   The size in bytes of the control.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dims[V4L2_CTRL_MAX_DIMS]</term>
      <listitem><para>
   The size of each dimension.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>nr_of_dims</term>
      <listitem><para>
   The number of dimensions in <parameter>dims</parameter>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cur</term>
      <listitem><para>
   The control's current value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p_new</term>
      <listitem><para>
   The control's new value represented via an union with provides
   a standard way of accessing control types
   through a pointer.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>p_cur</term>
      <listitem><para>
   The control's current value represented via an union with
   provides a standard way of accessing control types
   through a pointer.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-ctrl-ref">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_ctrl_ref</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_ctrl_ref</refname>
 <refpurpose>
     The control reference.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_ctrl_ref {
  struct list_head node;
  struct v4l2_ctrl_ref * next;
  struct v4l2_ctrl * ctrl;
  struct v4l2_ctrl_helper * helper;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>node</term>
      <listitem><para>
   List node for the sorted list.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>next</term>
      <listitem><para>
   Single-link list node for the hash.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ctrl</term>
      <listitem><para>
   The actual control information.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>helper</term>
      <listitem><para>
   Pointer to helper struct. Used internally in <function>prepare_ext_ctrls</function>.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Each control handler has a list of these refs. The list_head is used to
   keep a sorted-by-control-ID list of all controls, while the next pointer
   is used to link the control in the hash's bucket.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-v4l2-ctrl-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_ctrl_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_ctrl_handler</refname>
 <refpurpose>
     The control handler keeps track of all the
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_ctrl_handler {
  struct mutex _lock;
  struct mutex * lock;
  struct list_head ctrls;
  struct list_head ctrl_refs;
  struct v4l2_ctrl_ref * cached;
  struct v4l2_ctrl_ref ** buckets;
  v4l2_ctrl_notify_fnc notify;
  void * notify_priv;
  u16 nr_of_buckets;
  int error;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>_lock</term>
      <listitem><para>
   Default for <quote>lock</quote>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
   Lock to control access to this handler and its controls.
   May be replaced by the user right after init.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ctrls</term>
      <listitem><para>
   The list of controls owned by this handler.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ctrl_refs</term>
      <listitem><para>
   The list of control references.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cached</term>
      <listitem><para>
   The last found control reference. It is common that the same
   control is needed multiple times, so this is a simple
   optimization.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>buckets</term>
      <listitem><para>
   Buckets for the hashing. Allows for quick control lookup.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>notify</term>
      <listitem><para>
   A notify callback that is called whenever the control changes value.
   Note that the handler's lock is held when the notify function
   is called!
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>notify_priv</term>
      <listitem><para>
   Passed as argument to the v4l2_ctrl notify callback.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>nr_of_buckets</term>
      <listitem><para>
   Total number of buckets in the array.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>error</term>
      <listitem><para>
   The error code of the first failed control addition.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>controls</title>
<para>
   both the controls owned by the handler and those inherited
   from other handlers.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-v4l2-ctrl-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_ctrl_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_ctrl_config</refname>
 <refpurpose>
     Control configuration structure.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_ctrl_config {
  const struct v4l2_ctrl_ops * ops;
  const struct v4l2_ctrl_type_ops * type_ops;
  u32 id;
  const char * name;
  enum v4l2_ctrl_type type;
  s64 min;
  s64 max;
  u64 step;
  s64 def;
  u32 dims[V4L2_CTRL_MAX_DIMS];
  u32 elem_size;
  u32 flags;
  u64 menu_skip_mask;
  const char *const * qmenu;
  const s64 * qmenu_int;
  unsigned int is_private:1;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>ops</term>
      <listitem><para>
   The control ops.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type_ops</term>
      <listitem><para>
   The control type ops. Only needed for compound controls.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id</term>
      <listitem><para>
   The control ID.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name</term>
      <listitem><para>
   The control name.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type</term>
      <listitem><para>
   The control type.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>min</term>
      <listitem><para>
   The control's minimum value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max</term>
      <listitem><para>
   The control's maximum value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>step</term>
      <listitem><para>
   The control's step value for non-menu controls.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>def</term>
      <listitem><para>
   The control's default value.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dims[V4L2_CTRL_MAX_DIMS]</term>
      <listitem><para>
   The size of each dimension.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>elem_size</term>
      <listitem><para>
   The size in bytes of the control.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   The control's flags.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>menu_skip_mask</term>
      <listitem><para>
   The control's skip mask for menu controls. This makes it
   easy to skip menu items that are not valid. If bit X is set,
   then menu item X is skipped. Of course, this only works for
   menus with &lt;= 64 menu items. There are no menus that come
   close to that number, so this is OK. Should we ever need more,
   then this will have to be extended to a bit array.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>qmenu</term>
      <listitem><para>
   A const char * array for all menu items. Array entries that are
   empty strings ("") correspond to non-existing menu items (this
   is in addition to the menu_skip_mask above). The last entry
   must be NULL.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>qmenu_int</term>
      <listitem><para>
   A const s64 integer array for all menu items of the type
   V4L2_CTRL_TYPE_INTEGER_MENU.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>is_private</term>
      <listitem><para>
   If set, then this control is private to its handler and it
   will not be added to any other handlers.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-handler-init-class">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_handler_init_class</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_handler_init_class</refname>
 <refpurpose>
     Initialize the control handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>v4l2_ctrl_handler_init_class </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
   <paramdef>unsigned <parameter>nr_of_controls_hint</parameter></paramdef>
   <paramdef>struct lock_class_key * <parameter>key</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_of_controls_hint</parameter></term>
   <listitem>
    <para>
     A hint of how many controls this handler is
     expected to refer to. This is the total number, so including
     any inherited controls. It doesn't have to be precise, but if
     it is way off, then you either waste memory (too many buckets
     are allocated) or the control lookup becomes slower (not enough
     buckets are allocated, so there are more slow list lookups).
     It will always work, though.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>key</parameter></term>
   <listitem>
    <para>
     Used by the lock validator if CONFIG_LOCKDEP is set.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     Used by the lock validator if CONFIG_LOCKDEP is set.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns an error if the buckets could not be allocated. This error will
   also be stored in <parameter>hdl</parameter>-&gt;error.
   </para><para>

   Never use this call directly, always use the v4l2_ctrl_handler_init
   macro that hides the <parameter>key</parameter> and <parameter>name</parameter> arguments.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-handler-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_handler_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_handler_free</refname>
 <refpurpose>
     Free all controls owned by the handler and free the control list.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>v4l2_ctrl_handler_free </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Does nothing if <parameter>hdl</parameter> == NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_lock</refname>
 <refpurpose>
     Helper function to lock the handler associated with the control.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>v4l2_ctrl_lock </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control to lock.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-unlock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_unlock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_unlock</refname>
 <refpurpose>
     Helper function to unlock the handler associated with the control.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>v4l2_ctrl_unlock </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control to unlock.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-handler-setup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_handler_setup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_handler_setup</refname>
 <refpurpose>
     Call the s_ctrl op for all controls belonging to the handler to initialize the hardware to the current control values.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>v4l2_ctrl_handler_setup </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Button controls will be skipped, as are read-only controls.
   </para><para>

   If <parameter>hdl</parameter> == NULL, then this just returns 0.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-handler-log-status">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_handler_log_status</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_handler_log_status</refname>
 <refpurpose>
     Log all controls owned by the handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>v4l2_ctrl_handler_log_status </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
   <paramdef>const char * <parameter>prefix</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prefix</parameter></term>
   <listitem>
    <para>
     The prefix to use when logging the control values. If the
     prefix does not end with a space, then <quote>: </quote> will be added
     after the prefix. If <parameter>prefix</parameter> == NULL, then no prefix will be
     used.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   For use with VIDIOC_LOG_STATUS.
   </para><para>

   Does nothing if <parameter>hdl</parameter> == NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-new-custom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_new_custom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_new_custom</refname>
 <refpurpose>
     Allocate and initialize a new custom V4L2 control.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <function>v4l2_ctrl_new_custom </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-config">const struct v4l2_ctrl_config</link> * <parameter>cfg</parameter></paramdef>
   <paramdef>void * <parameter>priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cfg</parameter></term>
   <listitem>
    <para>
     The control's configuration data.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>priv</parameter></term>
   <listitem>
    <para>
     The control's driver-specific private data.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the <structname><link linkend="API-struct-v4l2-ctrl">v4l2_ctrl</link></structname> struct could not be allocated then NULL is returned
   and <parameter>hdl</parameter>-&gt;error is set to the error code (if it wasn't set already).
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-new-std">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_new_std</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_new_std</refname>
 <refpurpose>
     Allocate and initialize a new standard V4L2 non-menu control.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <function>v4l2_ctrl_new_std </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-ops">const struct v4l2_ctrl_ops</link> * <parameter>ops</parameter></paramdef>
   <paramdef>u32 <parameter>id</parameter></paramdef>
   <paramdef>s64 <parameter>min</parameter></paramdef>
   <paramdef>s64 <parameter>max</parameter></paramdef>
   <paramdef>u64 <parameter>step</parameter></paramdef>
   <paramdef>s64 <parameter>def</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     The control ops.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     The control ID.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     The control's minimum value.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     The control's maximum value.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>step</parameter></term>
   <listitem>
    <para>
     The control's step value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>def</parameter></term>
   <listitem>
    <para>
     The control's default value.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the <structname><link linkend="API-struct-v4l2-ctrl">v4l2_ctrl</link></structname> struct could not be allocated, or the control
   ID is not known, then NULL is returned and <parameter>hdl</parameter>-&gt;error is set to the
   appropriate error code (if it wasn't set already).
   </para><para>

   If <parameter>id</parameter> refers to a menu control, then this function will return NULL.
   </para><para>

   Use <function><link linkend="API-v4l2-ctrl-new-std-menu">v4l2_ctrl_new_std_menu</link></function> when adding menu controls.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-new-std-menu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_new_std_menu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_new_std_menu</refname>
 <refpurpose>
     Allocate and initialize a new standard V4L2 menu control.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <function>v4l2_ctrl_new_std_menu </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-ops">const struct v4l2_ctrl_ops</link> * <parameter>ops</parameter></paramdef>
   <paramdef>u32 <parameter>id</parameter></paramdef>
   <paramdef>u8 <parameter>max</parameter></paramdef>
   <paramdef>u64 <parameter>mask</parameter></paramdef>
   <paramdef>u8 <parameter>def</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     The control ops.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     The control ID.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     The control's maximum value.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     The control's skip mask for menu controls. This makes it
     easy to skip menu items that are not valid. If bit X is set,
     then menu item X is skipped. Of course, this only works for
     menus with &lt;= 64 menu items. There are no menus that come
     close to that number, so this is OK. Should we ever need more,
     then this will have to be extended to a bit array.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>def</parameter></term>
   <listitem>
    <para>
     The control's default value.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Same as <function><link linkend="API-v4l2-ctrl-new-std">v4l2_ctrl_new_std</link></function>, but <parameter>min</parameter> is set to 0 and the <parameter>mask</parameter> value
   determines which menu items are to be skipped.
   </para><para>

   If <parameter>id</parameter> refers to a non-menu control, then this function will return NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-new-std-menu-items">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_new_std_menu_items</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_new_std_menu_items</refname>
 <refpurpose>
     Create a new standard V4L2 menu control with driver specific menu.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <function>v4l2_ctrl_new_std_menu_items </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-ops">const struct v4l2_ctrl_ops</link> * <parameter>ops</parameter></paramdef>
   <paramdef>u32 <parameter>id</parameter></paramdef>
   <paramdef>u8 <parameter>max</parameter></paramdef>
   <paramdef>u64 <parameter>mask</parameter></paramdef>
   <paramdef>u8 <parameter>def</parameter></paramdef>
   <paramdef>const char *const * <parameter>qmenu</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     The control ops.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     The control ID.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     The control's maximum value.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     The control's skip mask for menu controls. This makes it
     easy to skip menu items that are not valid. If bit X is set,
     then menu item X is skipped. Of course, this only works for
     menus with &lt;= 64 menu items. There are no menus that come
     close to that number, so this is OK. Should we ever need more,
     then this will have to be extended to a bit array.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>def</parameter></term>
   <listitem>
    <para>
     The control's default value.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>qmenu</parameter></term>
   <listitem>
    <para>
     The new menu.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Same as <function><link linkend="API-v4l2-ctrl-new-std-menu">v4l2_ctrl_new_std_menu</link></function>, but <parameter>qmenu</parameter> will be the driver specific
   menu of this control.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-new-int-menu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_new_int_menu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_new_int_menu</refname>
 <refpurpose>
     Create a new standard V4L2 integer menu control.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <function>v4l2_ctrl_new_int_menu </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-ops">const struct v4l2_ctrl_ops</link> * <parameter>ops</parameter></paramdef>
   <paramdef>u32 <parameter>id</parameter></paramdef>
   <paramdef>u8 <parameter>max</parameter></paramdef>
   <paramdef>u8 <parameter>def</parameter></paramdef>
   <paramdef>const s64 * <parameter>qmenu_int</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     The control ops.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     The control ID.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     The control's maximum value.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>def</parameter></term>
   <listitem>
    <para>
     The control's default value.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>qmenu_int</parameter></term>
   <listitem>
    <para>
     The control's menu entries.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Same as <function><link linkend="API-v4l2-ctrl-new-std-menu">v4l2_ctrl_new_std_menu</link></function>, but <parameter>mask</parameter> is set to 0 and it additionaly
   takes as an argument an array of integers determining the menu items.
   </para><para>

   If <parameter>id</parameter> refers to a non-integer-menu control, then this function will return NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-add-ctrl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_add_ctrl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_add_ctrl</refname>
 <refpurpose>
     Add a control from another handler to this handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <function>v4l2_ctrl_add_ctrl </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control to add.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It will return NULL if it was unable to add the control reference.
   If the control already belonged to the handler, then it will do
   nothing and just return <parameter>ctrl</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-add-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_add_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_add_handler</refname>
 <refpurpose>
     Add all controls from handler <parameter>add</parameter> to handler <parameter>hdl</parameter>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>v4l2_ctrl_add_handler </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>add</parameter></paramdef>
   <paramdef>bool (*<parameter>filter</parameter>)
     <funcparams>const struct v4l2_ctrl *ctrl</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>add</parameter></term>
   <listitem>
    <para>
     The control handler whose controls you want to add to
     the <parameter>hdl</parameter> control handler.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filter</parameter></term>
   <listitem>
    <para>
     This function will filter which controls should be added.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Does nothing if either of the two handlers is a NULL pointer.
   If <parameter>filter</parameter> is NULL, then all controls are added. Otherwise only those
   controls for which <parameter>filter</parameter> returns true will be added.
   In case of an error <parameter>hdl</parameter>-&gt;error will be set to the error code (if it
   wasn't set already).
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-radio-filter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_radio_filter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_radio_filter</refname>
 <refpurpose>
     Standard filter for radio controls.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>v4l2_ctrl_radio_filter </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">const struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control that is filtered.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This will return true for any controls that are valid for radio device
   nodes. Those are all of the V4L2_CID_AUDIO_* user controls and all FM
   transmitter class controls.
   </para><para>

   This function is to be used with <function><link linkend="API-v4l2-ctrl-add-handler">v4l2_ctrl_add_handler</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-cluster">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_cluster</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_cluster</refname>
 <refpurpose>
     Mark all controls in the cluster as belonging to that cluster.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>v4l2_ctrl_cluster </function></funcdef>
   <paramdef>unsigned <parameter>ncontrols</parameter></paramdef>
   <paramdef>struct v4l2_ctrl ** <parameter>controls</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ncontrols</parameter></term>
   <listitem>
    <para>
     The number of controls in this cluster.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>controls</parameter></term>
   <listitem>
    <para>
     The cluster control array of size <parameter>ncontrols</parameter>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-auto-cluster">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_auto_cluster</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_auto_cluster</refname>
 <refpurpose>
     Mark all controls in the cluster as belonging to that cluster and set it up for autofoo/foo-type handling.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>v4l2_ctrl_auto_cluster </function></funcdef>
   <paramdef>unsigned <parameter>ncontrols</parameter></paramdef>
   <paramdef>struct v4l2_ctrl ** <parameter>controls</parameter></paramdef>
   <paramdef>u8 <parameter>manual_val</parameter></paramdef>
   <paramdef>bool <parameter>set_volatile</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ncontrols</parameter></term>
   <listitem>
    <para>
     The number of controls in this cluster.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>controls</parameter></term>
   <listitem>
    <para>
     The cluster control array of size <parameter>ncontrols</parameter>. The first control
     must be the 'auto' control (e.g. autogain, autoexposure, etc.)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>manual_val</parameter></term>
   <listitem>
    <para>
     The value for the first control in the cluster that equals the
     manual setting.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>set_volatile</parameter></term>
   <listitem>
    <para>
     If true, then all controls except the first auto control will
     be volatile.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use for control groups where one control selects some automatic feature and
   the other controls are only active whenever the automatic feature is turned
   off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
   red and blue balance, etc.
</para>
</refsect1>
<refsect1>
<title>The behavior of such controls is as follows</title>
<para>
   </para><para>

   When the autofoo control is set to automatic, then any manual controls
   are set to inactive and any reads will call g_volatile_ctrl (if the control
   was marked volatile).
   </para><para>

   When the autofoo control is set to manual, then any manual controls will
   be marked active, and any reads will just return the current value without
   going through g_volatile_ctrl.
   </para><para>

   In addition, this function will set the V4L2_CTRL_FLAG_UPDATE flag
   on the autofoo control and V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
   if autofoo is in auto mode.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-find">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_find</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_find</refname>
 <refpurpose>
     Find a control with the given ID.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <function>v4l2_ctrl_find </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl-handler">struct v4l2_ctrl_handler</link> * <parameter>hdl</parameter></paramdef>
   <paramdef>u32 <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hdl</parameter></term>
   <listitem>
    <para>
     The control handler.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     The control ID to find.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If <parameter>hdl</parameter> == NULL this will return NULL as well. Will lock the handler so
   do not use from inside <structname><link linkend="API-struct-v4l2-ctrl-ops">v4l2_ctrl_ops</link></structname>.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-activate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_activate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_activate</refname>
 <refpurpose>
     Make the control active or inactive.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>v4l2_ctrl_activate </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
   <paramdef>bool <parameter>active</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control to (de)activate.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>active</parameter></term>
   <listitem>
    <para>
     True if the control should become active.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This sets or clears the V4L2_CTRL_FLAG_INACTIVE flag atomically.
   Does nothing if <parameter>ctrl</parameter> == NULL.
   This will usually be called from within the s_ctrl op.
   The V4L2_EVENT_CTRL event will be generated afterwards.
   </para><para>

   This function assumes that the control handler is locked.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-grab">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_grab</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_grab</refname>
 <refpurpose>
     Mark the control as grabbed or not grabbed.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>v4l2_ctrl_grab </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
   <paramdef>bool <parameter>grabbed</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control to (de)activate.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>grabbed</parameter></term>
   <listitem>
    <para>
     True if the control should become grabbed.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically.
   Does nothing if <parameter>ctrl</parameter> == NULL.
   The V4L2_EVENT_CTRL event will be generated afterwards.
   This will usually be called when starting or stopping streaming in the
   driver.
   </para><para>

   This function assumes that the control handler is not locked and will
   take the lock itself.
</para>
</refsect1>
</refentry>

<refentry id="API---v4l2-ctrl-modify-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__v4l2_ctrl_modify_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__v4l2_ctrl_modify_range</refname>
 <refpurpose>
     Unlocked variant of <function><link linkend="API-v4l2-ctrl-modify-range">v4l2_ctrl_modify_range</link></function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__v4l2_ctrl_modify_range </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
   <paramdef>s64 <parameter>min</parameter></paramdef>
   <paramdef>s64 <parameter>max</parameter></paramdef>
   <paramdef>u64 <parameter>step</parameter></paramdef>
   <paramdef>s64 <parameter>def</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control to update.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     The control's minimum value.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     The control's maximum value.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>step</parameter></term>
   <listitem>
    <para>
     The control's step value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>def</parameter></term>
   <listitem>
    <para>
     The control's default value.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Update the range of a control on the fly. This works for control types
   INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
   <parameter>step</parameter> value is interpreted as a menu_skip_mask.
   </para><para>

   An error is returned if one of the range arguments is invalid for this
   control type.
   </para><para>

   This function assumes that the control handler is not locked and will
   take the lock itself.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-modify-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_modify_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_modify_range</refname>
 <refpurpose>
     Update the range of a control.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>v4l2_ctrl_modify_range </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
   <paramdef>s64 <parameter>min</parameter></paramdef>
   <paramdef>s64 <parameter>max</parameter></paramdef>
   <paramdef>u64 <parameter>step</parameter></paramdef>
   <paramdef>s64 <parameter>def</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control to update.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     The control's minimum value.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     The control's maximum value.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>step</parameter></term>
   <listitem>
    <para>
     The control's step value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>def</parameter></term>
   <listitem>
    <para>
     The control's default value.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Update the range of a control on the fly. This works for control types
   INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
   <parameter>step</parameter> value is interpreted as a menu_skip_mask.
   </para><para>

   An error is returned if one of the range arguments is invalid for this
   control type.
   </para><para>

   This function assumes that the control handler is not locked and will
   take the lock itself.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-notify">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_notify</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_notify</refname>
 <refpurpose>
     Function to set a notify callback for a control.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>v4l2_ctrl_notify </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
   <paramdef>v4l2_ctrl_notify_fnc <parameter>notify</parameter></paramdef>
   <paramdef>void * <parameter>priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>notify</parameter></term>
   <listitem>
    <para>
     The callback function.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>priv</parameter></term>
   <listitem>
    <para>
     The callback private handle, passed as argument to the callback.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function sets a callback function for the control. If <parameter>ctrl</parameter> is NULL,
   then it will do nothing. If <parameter>notify</parameter> is NULL, then the notify callback will
   be removed.
   </para><para>

   There can be only one notify. If another already exists, then a WARN_ON
   will be issued and the function will do nothing.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-get-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_get_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_get_name</refname>
 <refpurpose>
     Get the name of the control
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>v4l2_ctrl_get_name </function></funcdef>
   <paramdef>u32 <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     The control ID.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function returns the name of the given control ID or NULL if it isn't
   a known control.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-get-menu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_get_menu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_get_menu</refname>
 <refpurpose>
     Get the menu string array of the control
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * const * <function>v4l2_ctrl_get_menu </function></funcdef>
   <paramdef>u32 <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     The control ID.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function returns the NULL-terminated menu string array name of the
   given control ID or NULL if it isn't a known menu control.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-get-int-menu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_get_int_menu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_get_int_menu</refname>
 <refpurpose>
     Get the integer menu array of the control
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const s64 * <function>v4l2_ctrl_get_int_menu </function></funcdef>
   <paramdef>u32 <parameter>id</parameter></paramdef>
   <paramdef>u32 * <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     The control ID.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     The size of the integer array.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function returns the integer array of the given control ID or NULL if it
   if it isn't a known integer menu control.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-g-ctrl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_g_ctrl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_g_ctrl</refname>
 <refpurpose>
     Helper function to get the control's value from within a driver.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s32 <function>v4l2_ctrl_g_ctrl </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns the control's value safely by going through the control
   framework. This function will lock the control's handler, so it cannot be
   used from within the <structname><link linkend="API-struct-v4l2-ctrl-ops">v4l2_ctrl_ops</link></structname> functions.
   </para><para>

   This function is for integer type controls only.
</para>
</refsect1>
</refentry>

<refentry id="API---v4l2-ctrl-s-ctrl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__v4l2_ctrl_s_ctrl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__v4l2_ctrl_s_ctrl</refname>
 <refpurpose>
     Unlocked variant of <function>v4l2_ctrl_s_ctrl</function>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__v4l2_ctrl_s_ctrl </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
   <paramdef>s32 <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     The new value.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This set the control's new value safely by going through the control
   framework. This function will lock the control's handler, so it cannot be
   used from within the <structname><link linkend="API-struct-v4l2-ctrl-ops">v4l2_ctrl_ops</link></structname> functions.
   </para><para>

   This function is for integer type controls only.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-ctrl-g-ctrl-int64">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_ctrl_g_ctrl_int64</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_ctrl_g_ctrl_int64</refname>
 <refpurpose>
     Helper function to get a 64-bit control's value from within a driver.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s64 <function>v4l2_ctrl_g_ctrl_int64 </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns the control's value safely by going through the control
   framework. This function will lock the control's handler, so it cannot be
   used from within the <structname><link linkend="API-struct-v4l2-ctrl-ops">v4l2_ctrl_ops</link></structname> functions.
   </para><para>

   This function is for 64-bit integer type controls only.
</para>
</refsect1>
</refentry>

<refentry id="API---v4l2-ctrl-s-ctrl-int64">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__v4l2_ctrl_s_ctrl_int64</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__v4l2_ctrl_s_ctrl_int64</refname>
 <refpurpose>
     Unlocked variant of <function>v4l2_ctrl_s_ctrl_int64</function>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__v4l2_ctrl_s_ctrl_int64 </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-ctrl">struct v4l2_ctrl</link> * <parameter>ctrl</parameter></paramdef>
   <paramdef>s64 <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctrl</parameter></term>
   <listitem>
    <para>
     The control.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     The new value.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This set the control's new value safely by going through the control
   framework. This function will lock the control's handler, so it cannot be
   used from within the <structname><link linkend="API-struct-v4l2-ctrl-ops">v4l2_ctrl_ops</link></structname> functions.
   </para><para>

   This function is for 64-bit integer type controls only.
</para>
</refsect1>
</refentry>

<!-- include/media/v4l2-dv-timings.h -->
<refentry id="API-v4l2-check-dv-timings-fnc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_check_dv_timings_fnc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_check_dv_timings_fnc</refname>
 <refpurpose>
  timings check callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>typedef bool <function>v4l2_check_dv_timings_fnc </function></funcdef>
   <paramdef>const struct v4l2_dv_timings * <parameter>t</parameter></paramdef>
   <paramdef>void * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>t</parameter></term>
   <listitem>
    <para>
     the v4l2_dv_timings struct.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     a handle from the driver.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if the given timings are valid.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-valid-dv-timings">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_valid_dv_timings</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_valid_dv_timings</refname>
 <refpurpose>
     are these timings valid?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>v4l2_valid_dv_timings </function></funcdef>
   <paramdef>const struct v4l2_dv_timings * <parameter>t</parameter></paramdef>
   <paramdef>const struct v4l2_dv_timings_cap * <parameter>cap</parameter></paramdef>
   <paramdef><link linkend="API-v4l2-check-dv-timings-fnc">v4l2_check_dv_timings_fnc </link><parameter>fnc</parameter></paramdef>
   <paramdef>void * <parameter>fnc_handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>t</parameter></term>
   <listitem>
    <para>
     the v4l2_dv_timings struct.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cap</parameter></term>
   <listitem>
    <para>
     the v4l2_dv_timings_cap capabilities.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fnc</parameter></term>
   <listitem>
    <para>
     callback to check if this timing is OK. May be NULL.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fnc_handle</parameter></term>
   <listitem>
    <para>
     a handle that is passed on to <parameter>fnc</parameter>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if the given dv_timings struct is supported by the
   hardware capabilities and the callback function (if non-NULL), returns
   false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-enum-dv-timings-cap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_enum_dv_timings_cap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_enum_dv_timings_cap</refname>
 <refpurpose>
     Helper function to enumerate possible DV timings based on capabilities
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>v4l2_enum_dv_timings_cap </function></funcdef>
   <paramdef>struct v4l2_enum_dv_timings * <parameter>t</parameter></paramdef>
   <paramdef>const struct v4l2_dv_timings_cap * <parameter>cap</parameter></paramdef>
   <paramdef><link linkend="API-v4l2-check-dv-timings-fnc">v4l2_check_dv_timings_fnc </link><parameter>fnc</parameter></paramdef>
   <paramdef>void * <parameter>fnc_handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>t</parameter></term>
   <listitem>
    <para>
     the v4l2_enum_dv_timings struct.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cap</parameter></term>
   <listitem>
    <para>
     the v4l2_dv_timings_cap capabilities.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fnc</parameter></term>
   <listitem>
    <para>
     callback to check if this timing is OK. May be NULL.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fnc_handle</parameter></term>
   <listitem>
    <para>
     a handle that is passed on to <parameter>fnc</parameter>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This enumerates dv_timings using the full list of possible CEA-861 and DMT
   timings, filtering out any timings that are not supported based on the
   hardware capabilities and the callback function (if non-NULL).
   </para><para>

   If a valid timing for the given index is found, it will fill in <parameter>t</parameter> and
   return 0, otherwise it returns -EINVAL.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-find-dv-timings-cap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_find_dv_timings_cap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_find_dv_timings_cap</refname>
 <refpurpose>
     Find the closest timings struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>v4l2_find_dv_timings_cap </function></funcdef>
   <paramdef>struct v4l2_dv_timings * <parameter>t</parameter></paramdef>
   <paramdef>const struct v4l2_dv_timings_cap * <parameter>cap</parameter></paramdef>
   <paramdef>unsigned <parameter>pclock_delta</parameter></paramdef>
   <paramdef><link linkend="API-v4l2-check-dv-timings-fnc">v4l2_check_dv_timings_fnc </link><parameter>fnc</parameter></paramdef>
   <paramdef>void * <parameter>fnc_handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>t</parameter></term>
   <listitem>
    <para>
     the v4l2_enum_dv_timings struct.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cap</parameter></term>
   <listitem>
    <para>
     the v4l2_dv_timings_cap capabilities.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pclock_delta</parameter></term>
   <listitem>
    <para>
     maximum delta between t-&gt;pixelclock and the timing struct
     under consideration.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fnc</parameter></term>
   <listitem>
    <para>
     callback to check if a given timings struct is OK. May be NULL.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fnc_handle</parameter></term>
   <listitem>
    <para>
     a handle that is passed on to <parameter>fnc</parameter>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function tries to map the given timings to an entry in the
   full list of possible CEA-861 and DMT timings, filtering out any timings
   that are not supported based on the hardware capabilities and the callback
   function (if non-NULL).
   </para><para>

   On success it will fill in <parameter>t</parameter> with the found timings and it returns true.
   On failure it will return false.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-match-dv-timings">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_match_dv_timings</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_match_dv_timings</refname>
 <refpurpose>
     do two timings match?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>v4l2_match_dv_timings </function></funcdef>
   <paramdef>const struct v4l2_dv_timings * <parameter>measured</parameter></paramdef>
   <paramdef>const struct v4l2_dv_timings * <parameter>standard</parameter></paramdef>
   <paramdef>unsigned <parameter>pclock_delta</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>measured</parameter></term>
   <listitem>
    <para>
     the measured timings data.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>standard</parameter></term>
   <listitem>
    <para>
     the timings according to the standard.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pclock_delta</parameter></term>
   <listitem>
    <para>
     maximum delta in Hz between standard-&gt;pixelclock and
     the measured timings.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if the two timings match, returns false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-print-dv-timings">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_print_dv_timings</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_print_dv_timings</refname>
 <refpurpose>
     log the contents of a dv_timings struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>v4l2_print_dv_timings </function></funcdef>
   <paramdef>const char * <parameter>dev_prefix</parameter></paramdef>
   <paramdef>const char * <parameter>prefix</parameter></paramdef>
   <paramdef>const struct v4l2_dv_timings * <parameter>t</parameter></paramdef>
   <paramdef>bool <parameter>detailed</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_prefix</parameter></term>
   <listitem>
    <para>
     device prefix for each log line.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prefix</parameter></term>
   <listitem>
    <para>
     additional prefix for each log line, may be NULL.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>t</parameter></term>
   <listitem>
    <para>
     the timings data.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>detailed</parameter></term>
   <listitem>
    <para>
     if true, give a detailed log.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-v4l2-detect-cvt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_detect_cvt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_detect_cvt</refname>
 <refpurpose>
     detect if the given timings follow the CVT standard
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>v4l2_detect_cvt </function></funcdef>
   <paramdef>unsigned <parameter>frame_height</parameter></paramdef>
   <paramdef>unsigned <parameter>hfreq</parameter></paramdef>
   <paramdef>unsigned <parameter>vsync</parameter></paramdef>
   <paramdef>unsigned <parameter>active_width</parameter></paramdef>
   <paramdef>u32 <parameter>polarities</parameter></paramdef>
   <paramdef>bool <parameter>interlaced</parameter></paramdef>
   <paramdef>struct v4l2_dv_timings * <parameter>fmt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame_height</parameter></term>
   <listitem>
    <para>
     the total height of the frame (including blanking) in lines.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hfreq</parameter></term>
   <listitem>
    <para>
     the horizontal frequency in Hz.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vsync</parameter></term>
   <listitem>
    <para>
     the height of the vertical sync in lines.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>active_width</parameter></term>
   <listitem>
    <para>
     active width of image (does not include blanking). This
     information is needed only in case of version 2 of reduced blanking.
     In other cases, this parameter does not have any effect on timings.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>polarities</parameter></term>
   <listitem>
    <para>
     the horizontal and vertical polarities (same as struct
     v4l2_bt_timings polarities).
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>interlaced</parameter></term>
   <listitem>
    <para>
     if this flag is true, it indicates interlaced format
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     the resulting timings.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will attempt to detect if the given values correspond to a
   valid CVT format. If so, then it will return true, and fmt will be filled
   in with the found CVT timings.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-detect-gtf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_detect_gtf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_detect_gtf</refname>
 <refpurpose>
     detect if the given timings follow the GTF standard
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>v4l2_detect_gtf </function></funcdef>
   <paramdef>unsigned <parameter>frame_height</parameter></paramdef>
   <paramdef>unsigned <parameter>hfreq</parameter></paramdef>
   <paramdef>unsigned <parameter>vsync</parameter></paramdef>
   <paramdef>u32 <parameter>polarities</parameter></paramdef>
   <paramdef>bool <parameter>interlaced</parameter></paramdef>
   <paramdef>struct v4l2_fract <parameter>aspect</parameter></paramdef>
   <paramdef>struct v4l2_dv_timings * <parameter>fmt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame_height</parameter></term>
   <listitem>
    <para>
     the total height of the frame (including blanking) in lines.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hfreq</parameter></term>
   <listitem>
    <para>
     the horizontal frequency in Hz.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vsync</parameter></term>
   <listitem>
    <para>
     the height of the vertical sync in lines.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>polarities</parameter></term>
   <listitem>
    <para>
     the horizontal and vertical polarities (same as struct
     v4l2_bt_timings polarities).
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>interlaced</parameter></term>
   <listitem>
    <para>
     if this flag is true, it indicates interlaced format
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>aspect</parameter></term>
   <listitem>
    <para>
     preferred aspect ratio. GTF has no method of determining the
     aspect ratio in order to derive the image width from the
     image height, so it has to be passed explicitly. Usually
     the native screen aspect ratio is used for this. If it
     is not filled in correctly, then 16:9 will be assumed.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     the resulting timings.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will attempt to detect if the given values correspond to a
   valid GTF format. If so, then it will return true, and fmt will be filled
   in with the found GTF timings.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-calc-aspect-ratio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_calc_aspect_ratio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_calc_aspect_ratio</refname>
 <refpurpose>
     calculate the aspect ratio based on bytes 0x15 and 0x16 from the EDID.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct v4l2_fract <function>v4l2_calc_aspect_ratio </function></funcdef>
   <paramdef>u8 <parameter>hor_landscape</parameter></paramdef>
   <paramdef>u8 <parameter>vert_portrait</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hor_landscape</parameter></term>
   <listitem>
    <para>
     byte 0x15 from the EDID.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vert_portrait</parameter></term>
   <listitem>
    <para>
     byte 0x16 from the EDID.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Determines the aspect ratio from the EDID.
   See VESA Enhanced EDID standard, release A, rev 2, section 3.6.2:
   <quote>Horizontal and Vertical Screen Size or Aspect Ratio</quote>
</para>
</refsect1>
</refentry>

<!-- include/media/v4l2-event.h -->
<refentry id="API-struct-v4l2-kevent">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_kevent</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_kevent</refname>
 <refpurpose>
  Internal kernel event struct.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_kevent {
  struct list_head list;
  struct v4l2_subscribed_event * sev;
  struct v4l2_event event;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>list</term>
      <listitem><para>
List node for the v4l2_fh-&gt;available list.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sev</term>
      <listitem><para>
Pointer to parent v4l2_subscribed_event.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>event</term>
      <listitem><para>
The event itself.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-subscribed-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_subscribed_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_subscribed_event</refname>
 <refpurpose>
     Internal struct representing a subscribed event.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_subscribed_event {
  struct list_head list;
  u32 type;
  u32 id;
  u32 flags;
  struct v4l2_fh * fh;
  struct list_head node;
  const struct v4l2_subscribed_event_ops * ops;
  unsigned elems;
  unsigned first;
  unsigned in_use;
  struct v4l2_kevent events[];
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>list</term>
      <listitem><para>
   List node for the v4l2_fh-&gt;subscribed list.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type</term>
      <listitem><para>
   Event type.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id</term>
      <listitem><para>
   Associated object ID (e.g. control ID). 0 if there isn't any.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   Copy of v4l2_event_subscription-&gt;flags.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fh</term>
      <listitem><para>
   Filehandle that subscribed to this event.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>node</term>
      <listitem><para>
   List node that hooks into the object's event list (if there is one).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ops</term>
      <listitem><para>
   v4l2_subscribed_event_ops
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>elems</term>
      <listitem><para>
   The number of elements in the events array.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>first</term>
      <listitem><para>
   The index of the events containing the oldest available event.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>in_use</term>
      <listitem><para>
   The number of queued events.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>events[]</term>
      <listitem><para>
   An array of <parameter>elems</parameter> events.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- include/media/v4l2-flash-led-class.h -->
<refentry id="API-struct-v4l2-flash-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_flash_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_flash_config</refname>
 <refpurpose>
  V4L2 Flash sub-device initialization data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_flash_config {
  char dev_name[32];
  struct led_flash_setting torch_intensity;
  struct led_flash_setting indicator_intensity;
  u32 flash_faults;
  unsigned int has_external_strobe:1;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev_name[32]</term>
      <listitem><para>
the name of the media entity,
unique in the system
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>torch_intensity</term>
      <listitem><para>
constraints for the LED in torch mode
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>indicator_intensity</term>
      <listitem><para>
constraints for the indicator LED
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flash_faults</term>
      <listitem><para>
bitmask of flash faults that the LED flash class
device can report; corresponding LED_FAULT* bit
definitions are available in the header file
&lt;linux/led-class-flash.h&gt;
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>has_external_strobe</term>
      <listitem><para>
external strobe capability
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-flash">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_flash</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_flash</refname>
 <refpurpose>
     Flash sub-device context
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_flash {
  struct led_classdev_flash * fled_cdev;
  struct led_classdev_flash * iled_cdev;
  const struct v4l2_flash_ops * ops;
  struct v4l2_subdev sd;
  struct v4l2_ctrl_handler hdl;
  struct v4l2_ctrl ** ctrls;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>fled_cdev</term>
      <listitem><para>
   LED flash class device controlled by this sub-device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>iled_cdev</term>
      <listitem><para>
   LED class device representing indicator LED associated
   with the LED flash class device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ops</term>
      <listitem><para>
   V4L2 specific flash ops
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sd</term>
      <listitem><para>
   V4L2 sub-device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>hdl</term>
      <listitem><para>
   flash controls handler
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ctrls</term>
      <listitem><para>
   array of pointers to controls, whose values define
   the sub-device state
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-v4l2-flash-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_flash_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_flash_init</refname>
 <refpurpose>
     initialize V4L2 flash led sub-device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-v4l2-flash">struct v4l2_flash</link> * <function>v4l2_flash_init </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>struct device_node * <parameter>of_node</parameter></paramdef>
   <paramdef>struct led_classdev_flash * <parameter>fled_cdev</parameter></paramdef>
   <paramdef>struct led_classdev_flash * <parameter>iled_cdev</parameter></paramdef>
   <paramdef>const struct v4l2_flash_ops * <parameter>ops</parameter></paramdef>
   <paramdef><link linkend="API-struct-v4l2-flash-config">struct v4l2_flash_config</link> * <parameter>config</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     flash device, e.g. an I2C device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>of_node</parameter></term>
   <listitem>
    <para>
     of_node of the LED, may be NULL if the same as device's
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fled_cdev</parameter></term>
   <listitem>
    <para>
     LED flash class device to wrap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>iled_cdev</parameter></term>
   <listitem>
    <para>
     LED flash class device representing indicator LED associated
     with fled_cdev, may be NULL
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     V4L2 Flash device ops
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>config</parameter></term>
   <listitem>
    <para>
     initialization data for V4L2 Flash sub-device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Create V4L2 Flash sub-device wrapping given LED subsystem device.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A valid pointer, or, when an error occurs, the return
   value is encoded using <function>ERR_PTR</function>. Use <function>IS_ERR</function> to check and
   <function>PTR_ERR</function> to obtain the numeric return value.
</para>
</refsect1>
</refentry>

<refentry id="API-v4l2-flash-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_flash_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_flash_release</refname>
 <refpurpose>
     release V4L2 Flash sub-device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>v4l2_flash_release </function></funcdef>
   <paramdef><link linkend="API-struct-v4l2-flash">struct v4l2_flash</link> * <parameter>v4l2_flash</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>v4l2_flash</parameter></term>
   <listitem>
    <para>
     the V4L2 Flash sub-device to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release V4L2 Flash sub-device.
</para>
</refsect1>
</refentry>

<!-- include/media/v4l2-mediabus.h -->
<refentry id="API-enum-v4l2-mbus-type">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum v4l2_mbus_type</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum v4l2_mbus_type</refname>
 <refpurpose>
  media bus type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum v4l2_mbus_type {
  V4L2_MBUS_PARALLEL,
  V4L2_MBUS_BT656,
  V4L2_MBUS_CSI2
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>V4L2_MBUS_PARALLEL</term>
      <listitem><para>
parallel interface with hsync and vsync
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>V4L2_MBUS_BT656</term>
      <listitem><para>
parallel interface with embedded synchronisation, can
also be used for BT.1120
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>V4L2_MBUS_CSI2</term>
      <listitem><para>
MIPI CSI-2 serial interface
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-struct-v4l2-mbus-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_mbus_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_mbus_config</refname>
 <refpurpose>
     media bus configuration
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_mbus_config {
  enum v4l2_mbus_type type;
  unsigned int flags;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>type</term>
      <listitem><para>
   in: interface type
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   in / out: configuration flags, depending on <parameter>type</parameter>
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- include/media/v4l2-mem2mem.h -->
<refentry id="API-struct-v4l2-m2m-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_m2m_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_m2m_ops</refname>
 <refpurpose>
  mem-to-mem device driver callbacks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_m2m_ops {
  void (* device_run) (void *priv);
  int (* job_ready) (void *priv);
  void (* job_abort) (void *priv);
  void (* lock) (void *priv);
  void (* unlock) (void *priv);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>device_run</term>
      <listitem><para>
required. Begin the actual job (transaction) inside this
callback.
The job does NOT have to end before this callback returns
(and it will be the usual case). When the job finishes,
<function>v4l2_m2m_job_finish</function> has to be called.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>job_ready</term>
      <listitem><para>
optional. Should return 0 if the driver does not have a job
fully prepared to run yet (i.e. it will not be able to finish a
transaction without sleeping). If not provided, it will be
assumed that one source and one destination buffer are all
that is required for the driver to perform one full transaction.
This method may not sleep.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>job_abort</term>
      <listitem><para>
required. Informs the driver that it has to abort the currently
running transaction as soon as possible (i.e. as soon as it can
stop the device safely; e.g. in the next interrupt handler),
even if the transaction would not have been finished by then.
After the driver performs the necessary steps, it has to call
<function>v4l2_m2m_job_finish</function> (as if the transaction ended normally).
This function does not have to (and will usually not) wait
until the device enters a state when it can be stopped.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
optional. Define a driver's own lock callback, instead of using
m2m_ctx-&gt;q_lock.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>unlock</term>
      <listitem><para>
optional. Define a driver's own unlock callback, instead of
using m2m_ctx-&gt;q_lock.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-v4l2-m2m-num-src-bufs-ready">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_m2m_num_src_bufs_ready</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_m2m_num_src_bufs_ready</refname>
 <refpurpose>
     return the number of source buffers ready for use
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>v4l2_m2m_num_src_bufs_ready </function></funcdef>
   <paramdef>struct v4l2_m2m_ctx * <parameter>m2m_ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m2m_ctx</parameter></term>
   <listitem>
    <para>
     pointer to struct v4l2_m2m_ctx
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-v4l2-m2m-num-dst-bufs-ready">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_m2m_num_dst_bufs_ready</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_m2m_num_dst_bufs_ready</refname>
 <refpurpose>
     return the number of destination buffers ready for use
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>v4l2_m2m_num_dst_bufs_ready </function></funcdef>
   <paramdef>struct v4l2_m2m_ctx * <parameter>m2m_ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m2m_ctx</parameter></term>
   <listitem>
    <para>
     pointer to struct v4l2_m2m_ctx
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-v4l2-m2m-next-src-buf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_m2m_next_src_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_m2m_next_src_buf</refname>
 <refpurpose>
     return next source buffer from the list of ready buffers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>v4l2_m2m_next_src_buf </function></funcdef>
   <paramdef>struct v4l2_m2m_ctx * <parameter>m2m_ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m2m_ctx</parameter></term>
   <listitem>
    <para>
     pointer to struct v4l2_m2m_ctx
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-v4l2-m2m-next-dst-buf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_m2m_next_dst_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_m2m_next_dst_buf</refname>
 <refpurpose>
     return next destination buffer from the list of ready buffers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>v4l2_m2m_next_dst_buf </function></funcdef>
   <paramdef>struct v4l2_m2m_ctx * <parameter>m2m_ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m2m_ctx</parameter></term>
   <listitem>
    <para>
     pointer to struct v4l2_m2m_ctx
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-v4l2-m2m-get-src-vq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_m2m_get_src_vq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_m2m_get_src_vq</refname>
 <refpurpose>
     return vb2_queue for source buffers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-vb2-queue">struct vb2_queue</link> * <function>v4l2_m2m_get_src_vq </function></funcdef>
   <paramdef>struct v4l2_m2m_ctx * <parameter>m2m_ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m2m_ctx</parameter></term>
   <listitem>
    <para>
     pointer to struct v4l2_m2m_ctx
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-v4l2-m2m-get-dst-vq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_m2m_get_dst_vq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_m2m_get_dst_vq</refname>
 <refpurpose>
     return vb2_queue for destination buffers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-vb2-queue">struct vb2_queue</link> * <function>v4l2_m2m_get_dst_vq </function></funcdef>
   <paramdef>struct v4l2_m2m_ctx * <parameter>m2m_ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m2m_ctx</parameter></term>
   <listitem>
    <para>
     pointer to struct v4l2_m2m_ctx
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-v4l2-m2m-src-buf-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_m2m_src_buf_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_m2m_src_buf_remove</refname>
 <refpurpose>
     take off a source buffer from the list of ready buffers and return it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>v4l2_m2m_src_buf_remove </function></funcdef>
   <paramdef>struct v4l2_m2m_ctx * <parameter>m2m_ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m2m_ctx</parameter></term>
   <listitem>
    <para>
     pointer to struct v4l2_m2m_ctx
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-v4l2-m2m-dst-buf-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>v4l2_m2m_dst_buf_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>v4l2_m2m_dst_buf_remove</refname>
 <refpurpose>
     take off a destination buffer from the list of ready buffers and return it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>v4l2_m2m_dst_buf_remove </function></funcdef>
   <paramdef>struct v4l2_m2m_ctx * <parameter>m2m_ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m2m_ctx</parameter></term>
   <listitem>
    <para>
     pointer to struct v4l2_m2m_ctx
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- include/media/v4l2-of.h -->
<refentry id="API-struct-v4l2-of-bus-mipi-csi2">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_of_bus_mipi_csi2</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_of_bus_mipi_csi2</refname>
 <refpurpose>
  MIPI CSI-2 bus data structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_of_bus_mipi_csi2 {
  unsigned int flags;
  unsigned char data_lanes[4];
  unsigned char clock_lane;
  unsigned short num_data_lanes;
  bool lane_polarities[5];
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>flags</term>
      <listitem><para>
media bus (V4L2_MBUS_*) flags
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>data_lanes[4]</term>
      <listitem><para>
an array of physical data lane indexes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>clock_lane</term>
      <listitem><para>
physical lane index of the clock lane
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_data_lanes</term>
      <listitem><para>
number of data lanes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lane_polarities[5]</term>
      <listitem><para>
polarity of the lanes. The order is the same of
the physical lanes.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-of-bus-parallel">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_of_bus_parallel</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_of_bus_parallel</refname>
 <refpurpose>
     parallel data bus data structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_of_bus_parallel {
  unsigned int flags;
  unsigned char bus_width;
  unsigned char data_shift;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   media bus (V4L2_MBUS_*) flags
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus_width</term>
      <listitem><para>
   bus width in bits
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>data_shift</term>
      <listitem><para>
   data shift in bits
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-of-endpoint">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_of_endpoint</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_of_endpoint</refname>
 <refpurpose>
     the endpoint data structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_of_endpoint {
  struct of_endpoint base;
  enum v4l2_mbus_type bus_type;
  union bus;
  u64 * link_frequencies;
  unsigned int nr_of_link_frequencies;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>base</term>
      <listitem><para>
   struct of_endpoint containing port, id, and local of_node
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus_type</term>
      <listitem><para>
   bus type
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus</term>
      <listitem><para>
   bus configuration data structure
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>link_frequencies</term>
      <listitem><para>
   array of supported link frequencies
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>nr_of_link_frequencies</term>
      <listitem><para>
   number of elements in link_frequenccies array
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-of-link">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_of_link</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_of_link</refname>
 <refpurpose>
     a link between two endpoints
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_of_link {
  struct device_node * local_node;
  unsigned int local_port;
  struct device_node * remote_node;
  unsigned int remote_port;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>local_node</term>
      <listitem><para>
   pointer to device_node of this endpoint
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>local_port</term>
      <listitem><para>
   identifier of the port this endpoint belongs to
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>remote_node</term>
      <listitem><para>
   pointer to device_node of the remote endpoint
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>remote_port</term>
      <listitem><para>
   identifier of the port the remote endpoint belongs to
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- include/media/v4l2-subdev.h -->
<refentry id="API-struct-v4l2-subdev-core-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_subdev_core_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_subdev_core_ops</refname>
 <refpurpose>
  Define core ops callbacks for subdevs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_subdev_core_ops {
  int (* log_status) (struct v4l2_subdev *sd);
  int (* s_io_pin_config) (struct v4l2_subdev *sd, size_t n,struct v4l2_subdev_io_pin_config *pincfg);
  int (* init) (struct v4l2_subdev *sd, u32 val);
  int (* load_fw) (struct v4l2_subdev *sd);
  int (* reset) (struct v4l2_subdev *sd, u32 val);
  int (* s_gpio) (struct v4l2_subdev *sd, u32 val);
  int (* queryctrl) (struct v4l2_subdev *sd, struct v4l2_queryctrl *qc);
  int (* g_ctrl) (struct v4l2_subdev *sd, struct v4l2_control *ctrl);
  int (* s_ctrl) (struct v4l2_subdev *sd, struct v4l2_control *ctrl);
  int (* g_ext_ctrls) (struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
  int (* s_ext_ctrls) (struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
  int (* try_ext_ctrls) (struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
  int (* querymenu) (struct v4l2_subdev *sd, struct v4l2_querymenu *qm);
  long (* ioctl) (struct v4l2_subdev *sd, unsigned int cmd, void *arg);
#ifdef CONFIG_COMPAT
  long (* compat_ioctl32) (struct v4l2_subdev *sd, unsigned int cmd,unsigned long arg);
#endif
#ifdef CONFIG_VIDEO_ADV_DEBUG
  int (* g_register) (struct v4l2_subdev *sd, struct v4l2_dbg_register *reg);
  int (* s_register) (struct v4l2_subdev *sd, const struct v4l2_dbg_register *reg);
#endif
  int (* s_power) (struct v4l2_subdev *sd, int on);
  int (* interrupt_service_routine) (struct v4l2_subdev *sd,u32 status, bool *handled);
  int (* subscribe_event) (struct v4l2_subdev *sd, struct v4l2_fh *fh,struct v4l2_event_subscription *sub);
  int (* unsubscribe_event) (struct v4l2_subdev *sd, struct v4l2_fh *fh,struct v4l2_event_subscription *sub);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>log_status</term>
      <listitem><para>
callback for VIDIOC_LOG_STATUS ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_io_pin_config</term>
      <listitem><para>
configure one or more chip I/O pins for chips that
multiplex different internal signal pads out to IO pins.  This function
takes a pointer to an array of 'n' pin configuration entries, one for
each pin being configured.  This function could be called at times
other than just subdevice initialization.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>init</term>
      <listitem><para>
initialize the sensor registers to some sort of reasonable default
values. Do not use for new drivers and should be removed in existing
drivers.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>load_fw</term>
      <listitem><para>
load firmware.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>reset</term>
      <listitem><para>
generic reset command. The argument selects which subsystems to
reset. Passing 0 will always reset the whole chip. Do not use for new
drivers without discussing this first on the linux-media mailinglist.
There should be no reason normally to reset a device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_gpio</term>
      <listitem><para>
set GPIO pins. Very simple right now, might need to be extended with
a direction argument if needed.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>queryctrl</term>
      <listitem><para>
callback for VIDIOC_QUERYCTL ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_ctrl</term>
      <listitem><para>
callback for VIDIOC_G_CTRL ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_ctrl</term>
      <listitem><para>
callback for VIDIOC_S_CTRL ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_ext_ctrls</term>
      <listitem><para>
callback for VIDIOC_G_EXT_CTRLS ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_ext_ctrls</term>
      <listitem><para>
callback for VIDIOC_S_EXT_CTRLS ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>try_ext_ctrls</term>
      <listitem><para>
callback for VIDIOC_TRY_EXT_CTRLS ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>querymenu</term>
      <listitem><para>
callback for VIDIOC_QUERYMENU ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ioctl</term>
      <listitem><para>
called at the end of <function>ioctl</function> syscall handler at the V4L2 core.
used to provide support for private ioctls used on the driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>compat_ioctl32</term>
      <listitem><para>
called when a 32 bits application uses a 64 bits Kernel,
in order to fix data passed from/to userspace.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_register</term>
      <listitem><para>
callback for VIDIOC_G_REGISTER ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_register</term>
      <listitem><para>
callback for VIDIOC_G_REGISTER ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_power</term>
      <listitem><para>
puts subdevice in power saving mode (on == 0) or normal operation
mode (on == 1).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>interrupt_service_routine</term>
      <listitem><para>
Called by the bridge chip's interrupt service
handler, when an interrupt status has be raised due to this subdev,
so that this subdev can handle the details.  It may schedule work to be
performed later.  It must not sleep.  *Called from an IRQ context*.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>subscribe_event</term>
      <listitem><para>
used by the drivers to request the control framework that
for it to be warned when the value of a control changes.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>unsubscribe_event</term>
      <listitem><para>
remove event subscription from the control framework.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-subdev-tuner-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_subdev_tuner_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_subdev_tuner_ops</refname>
 <refpurpose>
     Callbacks used when v4l device was opened in radio mode.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_subdev_tuner_ops {
  int (* s_radio) (struct v4l2_subdev *sd);
  int (* s_frequency) (struct v4l2_subdev *sd, const struct v4l2_frequency *freq);
  int (* g_frequency) (struct v4l2_subdev *sd, struct v4l2_frequency *freq);
  int (* enum_freq_bands) (struct v4l2_subdev *sd, struct v4l2_frequency_band *band);
  int (* g_tuner) (struct v4l2_subdev *sd, struct v4l2_tuner *vt);
  int (* s_tuner) (struct v4l2_subdev *sd, const struct v4l2_tuner *vt);
  int (* g_modulator) (struct v4l2_subdev *sd, struct v4l2_modulator *vm);
  int (* s_modulator) (struct v4l2_subdev *sd, const struct v4l2_modulator *vm);
  int (* s_type_addr) (struct v4l2_subdev *sd, struct tuner_setup *type);
  int (* s_config) (struct v4l2_subdev *sd, const struct v4l2_priv_tun_config *config);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>s_radio</term>
      <listitem><para>
   callback for VIDIOC_S_RADIO ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_frequency</term>
      <listitem><para>
   callback for VIDIOC_S_FREQUENCY ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_frequency</term>
      <listitem><para>
   callback for VIDIOC_G_FREQUENCY ioctl handler code.
   freq-&gt;type must be filled in. Normally done by video_ioctl2
   or the bridge driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enum_freq_bands</term>
      <listitem><para>
   callback for VIDIOC_ENUM_FREQ_BANDS ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_tuner</term>
      <listitem><para>
   callback for VIDIOC_G_TUNER ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_tuner</term>
      <listitem><para>
   callback for VIDIOC_S_TUNER ioctl handler code. vt-&gt;type must be
   filled in. Normally done by video_ioctl2 or the
   bridge driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_modulator</term>
      <listitem><para>
   callback for VIDIOC_G_MODULATOR ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_modulator</term>
      <listitem><para>
   callback for VIDIOC_S_MODULATOR ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_type_addr</term>
      <listitem><para>
   sets tuner type and its I2C addr.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_config</term>
      <listitem><para>
   sets tda9887 specific stuff, like port1, port2 and qss
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-subdev-audio-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_subdev_audio_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_subdev_audio_ops</refname>
 <refpurpose>
     Callbacks used for audio-related settings
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_subdev_audio_ops {
  int (* s_clock_freq) (struct v4l2_subdev *sd, u32 freq);
  int (* s_i2s_clock_freq) (struct v4l2_subdev *sd, u32 freq);
  int (* s_routing) (struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
  int (* s_stream) (struct v4l2_subdev *sd, int enable);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>s_clock_freq</term>
      <listitem><para>
   set the frequency (in Hz) of the audio clock output.
   Used to slave an audio processor to the video decoder, ensuring that
   audio and video remain synchronized. Usual values for the frequency
   are 48000, 44100 or 32000 Hz. If the frequency is not supported, then
   -EINVAL is returned.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_i2s_clock_freq</term>
      <listitem><para>
   sets I2S speed in bps. This is used to provide a standard
   way to select I2S clock used by driving digital audio streams at some
   board designs. Usual values for the frequency are 1024000 and 2048000.
   If the frequency is not supported, then -EINVAL is returned.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_routing</term>
      <listitem><para>
   used to define the input and/or output pins of an audio chip,
   and any additional configuration data.
   Never attempt to use user-level input IDs (e.g. Composite, S-Video,
   Tuner) at this level. An i2c device shouldn't know about whether an
   input pin is connected to a Composite connector, become on another
   board or platform it might be connected to something else entirely.
   The calling driver is responsible for mapping a user-level input to
   the right pins on the i2c device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_stream</term>
      <listitem><para>
   used to notify the audio code that stream will start or has
   stopped.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-mbus-frame-desc-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_mbus_frame_desc_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_mbus_frame_desc_entry</refname>
 <refpurpose>
     media bus frame description structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_mbus_frame_desc_entry {
  u16 flags;
  u32 pixelcode;
  u32 length;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   V4L2_MBUS_FRAME_DESC_FL_* flags
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pixelcode</term>
      <listitem><para>
   media bus pixel code, valid if FRAME_DESC_FL_BLOB is not set
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>length</term>
      <listitem><para>
   number of octets per frame, valid if V4L2_MBUS_FRAME_DESC_FL_BLOB
   is set
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-mbus-frame-desc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_mbus_frame_desc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_mbus_frame_desc</refname>
 <refpurpose>
     media bus data frame description
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_mbus_frame_desc {
  struct v4l2_mbus_frame_desc_entry entry[V4L2_FRAME_DESC_ENTRY_MAX];
  unsigned short num_entries;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>entry[V4L2_FRAME_DESC_ENTRY_MAX]</term>
      <listitem><para>
   frame descriptors array
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_entries</term>
      <listitem><para>
   number of entries in <parameter>entry</parameter> array
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-subdev-video-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_subdev_video_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_subdev_video_ops</refname>
 <refpurpose>
     Callbacks used when v4l device was opened in video mode.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_subdev_video_ops {
  int (* s_routing) (struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
  int (* s_crystal_freq) (struct v4l2_subdev *sd, u32 freq, u32 flags);
  int (* g_std) (struct v4l2_subdev *sd, v4l2_std_id *norm);
  int (* s_std) (struct v4l2_subdev *sd, v4l2_std_id norm);
  int (* s_std_output) (struct v4l2_subdev *sd, v4l2_std_id std);
  int (* g_std_output) (struct v4l2_subdev *sd, v4l2_std_id *std);
  int (* querystd) (struct v4l2_subdev *sd, v4l2_std_id *std);
  int (* g_tvnorms) (struct v4l2_subdev *sd, v4l2_std_id *std);
  int (* g_tvnorms_output) (struct v4l2_subdev *sd, v4l2_std_id *std);
  int (* g_input_status) (struct v4l2_subdev *sd, u32 *status);
  int (* s_stream) (struct v4l2_subdev *sd, int enable);
  int (* cropcap) (struct v4l2_subdev *sd, struct v4l2_cropcap *cc);
  int (* g_crop) (struct v4l2_subdev *sd, struct v4l2_crop *crop);
  int (* s_crop) (struct v4l2_subdev *sd, const struct v4l2_crop *crop);
  int (* g_parm) (struct v4l2_subdev *sd, struct v4l2_streamparm *param);
  int (* s_parm) (struct v4l2_subdev *sd, struct v4l2_streamparm *param);
  int (* g_frame_interval) (struct v4l2_subdev *sd,struct v4l2_subdev_frame_interval *interval);
  int (* s_frame_interval) (struct v4l2_subdev *sd,struct v4l2_subdev_frame_interval *interval);
  int (* s_dv_timings) (struct v4l2_subdev *sd,struct v4l2_dv_timings *timings);
  int (* g_dv_timings) (struct v4l2_subdev *sd,struct v4l2_dv_timings *timings);
  int (* query_dv_timings) (struct v4l2_subdev *sd,struct v4l2_dv_timings *timings);
  int (* g_mbus_config) (struct v4l2_subdev *sd,struct v4l2_mbus_config *cfg);
  int (* s_mbus_config) (struct v4l2_subdev *sd,const struct v4l2_mbus_config *cfg);
  int (* s_rx_buffer) (struct v4l2_subdev *sd, void *buf,unsigned int *size);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>s_routing</term>
      <listitem><para>
   see s_routing in audio_ops, except this version is for video
   devices.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_crystal_freq</term>
      <listitem><para>
   sets the frequency of the crystal used to generate the
   clocks in Hz. An extra flags field allows device specific configuration
   regarding clock frequency dividers, etc. If not used, then set flags
   to 0. If the frequency is not supported, then -EINVAL is returned.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_std</term>
      <listitem><para>
   callback for VIDIOC_G_STD ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_std</term>
      <listitem><para>
   callback for VIDIOC_S_STD ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_std_output</term>
      <listitem><para>
   set v4l2_std_id for video OUTPUT devices. This is ignored by
   video input devices.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_std_output</term>
      <listitem><para>
   get current standard for video OUTPUT devices. This is ignored
   by video input devices.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>querystd</term>
      <listitem><para>
   callback for VIDIOC_QUERYSTD ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_tvnorms</term>
      <listitem><para>
   get v4l2_std_id with all standards supported by the video
   CAPTURE device. This is ignored by video output devices.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_tvnorms_output</term>
      <listitem><para>
   get v4l2_std_id with all standards supported by the video
   OUTPUT device. This is ignored by video capture devices.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_input_status</term>
      <listitem><para>
   get input status. Same as the status field in the v4l2_input
   struct.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_stream</term>
      <listitem><para>
   used to notify the driver that a video stream will start or has
   stopped.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cropcap</term>
      <listitem><para>
   callback for VIDIOC_CROPCAP ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_crop</term>
      <listitem><para>
   callback for VIDIOC_G_CROP ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_crop</term>
      <listitem><para>
   callback for VIDIOC_S_CROP ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_parm</term>
      <listitem><para>
   callback for VIDIOC_G_PARM ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_parm</term>
      <listitem><para>
   callback for VIDIOC_S_PARM ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_frame_interval</term>
      <listitem><para>
   callback for VIDIOC_G_FRAMEINTERVAL ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_frame_interval</term>
      <listitem><para>
   callback for VIDIOC_S_FRAMEINTERVAL ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_dv_timings</term>
      <listitem><para>
   Set custom dv timings in the sub device. This is used
   when sub device is capable of setting detailed timing information
   in the hardware to generate/detect the video signal.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_dv_timings</term>
      <listitem><para>
   Get custom dv timings in the sub device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>query_dv_timings</term>
      <listitem><para>
   callback for VIDIOC_QUERY_DV_TIMINGS ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_mbus_config</term>
      <listitem><para>
   get supported mediabus configurations
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_mbus_config</term>
      <listitem><para>
   set a certain mediabus configuration. This operation is added
   for compatibility with soc-camera drivers and should not be used by new
   software.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_rx_buffer</term>
      <listitem><para>
   set a host allocated memory buffer for the subdev. The subdev
   can adjust <parameter>size</parameter> to a lower value and must not write more data to the
   buffer starting at <parameter>data</parameter> than the original value of <parameter>size</parameter>.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-subdev-vbi-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_subdev_vbi_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_subdev_vbi_ops</refname>
 <refpurpose>
     Callbacks used when v4l device was opened in video mode via the vbi device node.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_subdev_vbi_ops {
  int (* decode_vbi_line) (struct v4l2_subdev *sd, struct v4l2_decode_vbi_line *vbi_line);
  int (* s_vbi_data) (struct v4l2_subdev *sd, const struct v4l2_sliced_vbi_data *vbi_data);
  int (* g_vbi_data) (struct v4l2_subdev *sd, struct v4l2_sliced_vbi_data *vbi_data);
  int (* g_sliced_vbi_cap) (struct v4l2_subdev *sd, struct v4l2_sliced_vbi_cap *cap);
  int (* s_raw_fmt) (struct v4l2_subdev *sd, struct v4l2_vbi_format *fmt);
  int (* g_sliced_fmt) (struct v4l2_subdev *sd, struct v4l2_sliced_vbi_format *fmt);
  int (* s_sliced_fmt) (struct v4l2_subdev *sd, struct v4l2_sliced_vbi_format *fmt);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>decode_vbi_line</term>
      <listitem><para>
   video decoders that support sliced VBI need to implement
   this ioctl. Field p of the v4l2_sliced_vbi_line struct is set to the
   start of the VBI data that was generated by the decoder. The driver
   then parses the sliced VBI data and sets the other fields in the
   struct accordingly. The pointer p is updated to point to the start of
   the payload which can be copied verbatim into the data field of the
   v4l2_sliced_vbi_data struct. If no valid VBI data was found, then the
   type field is set to 0 on return.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_vbi_data</term>
      <listitem><para>
   used to generate VBI signals on a video signal.
   v4l2_sliced_vbi_data is filled with the data packets that should be
   output. Note that if you set the line field to 0, then that VBI signal
   is disabled. If no valid VBI data was found, then the type field is
   set to 0 on return.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_vbi_data</term>
      <listitem><para>
   used to obtain the sliced VBI packet from a readback register.
   Not all video decoders support this. If no data is available because
   the readback register contains invalid or erroneous data -EIO is
   returned. Note that you must fill in the 'id' member and the 'field'
   member (to determine whether CC data from the first or second field
   should be obtained).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_sliced_vbi_cap</term>
      <listitem><para>
   callback for VIDIOC_SLICED_VBI_CAP ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_raw_fmt</term>
      <listitem><para>
   setup the video encoder/decoder for raw VBI.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_sliced_fmt</term>
      <listitem><para>
   retrieve the current sliced VBI settings.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_sliced_fmt</term>
      <listitem><para>
   setup the sliced VBI settings.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-subdev-sensor-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_subdev_sensor_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_subdev_sensor_ops</refname>
 <refpurpose>
     v4l2-subdev sensor operations
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_subdev_sensor_ops {
  int (* g_skip_top_lines) (struct v4l2_subdev *sd, u32 *lines);
  int (* g_skip_frames) (struct v4l2_subdev *sd, u32 *frames);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>g_skip_top_lines</term>
      <listitem><para>
   number of lines at the top of the image to be skipped.
   This is needed for some sensors, which always corrupt
   several top lines of the output image, or which send their
   metadata in them.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>g_skip_frames</term>
      <listitem><para>
   number of frames to skip at stream start. This is needed for
   buggy sensors that generate faulty frames when they are
   turned on.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-v4l2-subdev-pad-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct v4l2_subdev_pad_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct v4l2_subdev_pad_ops</refname>
 <refpurpose>
     v4l2-subdev pad level operations
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct v4l2_subdev_pad_ops {
  int (* enum_mbus_code) (struct v4l2_subdev *sd,struct v4l2_subdev_pad_config *cfg,struct v4l2_subdev_mbus_code_enum *code);
  int (* enum_frame_size) (struct v4l2_subdev *sd,struct v4l2_subdev_pad_config *cfg,struct v4l2_subdev_frame_size_enum *fse);
  int (* enum_frame_interval) (struct v4l2_subdev *sd,struct v4l2_subdev_pad_config *cfg,struct v4l2_subdev_frame_interval_enum *fie);
  int (* get_fmt) (struct v4l2_subdev *sd,struct v4l2_subdev_pad_config *cfg,struct v4l2_subdev_format *format);
  int (* set_fmt) (struct v4l2_subdev *sd,struct v4l2_subdev_pad_config *cfg,struct v4l2_subdev_format *format);
  int (* get_selection) (struct v4l2_subdev *sd,struct v4l2_subdev_pad_config *cfg,struct v4l2_subdev_selection *sel);
  int (* set_selection) (struct v4l2_subdev *sd,struct v4l2_subdev_pad_config *cfg,struct v4l2_subdev_selection *sel);
  int (* get_edid) (struct v4l2_subdev *sd, struct v4l2_edid *edid);
  int (* set_edid) (struct v4l2_subdev *sd, struct v4l2_edid *edid);
  int (* dv_timings_cap) (struct v4l2_subdev *sd,struct v4l2_dv_timings_cap *cap);
  int (* enum_dv_timings) (struct v4l2_subdev *sd,struct v4l2_enum_dv_timings *timings);
#ifdef CONFIG_MEDIA_CONTROLLER
  int (* link_validate) (struct v4l2_subdev *sd, struct media_link *link,struct v4l2_subdev_format *source_fmt,struct v4l2_subdev_format *sink_fmt);
#endif
  int (* get_frame_desc) (struct v4l2_subdev *sd, unsigned int pad,struct v4l2_mbus_frame_desc *fd);
  int (* set_frame_desc) (struct v4l2_subdev *sd, unsigned int pad,struct v4l2_mbus_frame_desc *fd);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>enum_mbus_code</term>
      <listitem><para>
   callback for VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl handler
   code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enum_frame_size</term>
      <listitem><para>
   callback for VIDIOC_SUBDEV_ENUM_FRAME_SIZE ioctl handler
   code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enum_frame_interval</term>
      <listitem><para>
   callback for VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL ioctl
   handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_fmt</term>
      <listitem><para>
   callback for VIDIOC_SUBDEV_G_FMT ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_fmt</term>
      <listitem><para>
   callback for VIDIOC_SUBDEV_S_FMT ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_selection</term>
      <listitem><para>
   callback for VIDIOC_SUBDEV_G_SELECTION ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_selection</term>
      <listitem><para>
   callback for VIDIOC_SUBDEV_S_SELECTION ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_edid</term>
      <listitem><para>
   callback for VIDIOC_SUBDEV_G_EDID ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_edid</term>
      <listitem><para>
   callback for VIDIOC_SUBDEV_S_EDID ioctl handler code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dv_timings_cap</term>
      <listitem><para>
   callback for VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl handler
   code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enum_dv_timings</term>
      <listitem><para>
   callback for VIDIOC_SUBDEV_ENUM_DV_TIMINGS ioctl handler
   code.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>link_validate</term>
      <listitem><para>
   used by the media controller code to check if the links
   that belongs to a pipeline can be used for stream.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_frame_desc</term>
      <listitem><para>
   get the current low level media bus frame parameters.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_frame_desc</term>
      <listitem><para>
   set the low level media bus frame parameters, <parameter>fd</parameter> array
   may be adjusted by the subdev driver to device capabilities.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- include/media/videobuf2-core.h -->
<refentry id="API-struct-vb2-mem-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct vb2_mem_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct vb2_mem_ops</refname>
 <refpurpose>
  memory handling/memory allocator operations
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct vb2_mem_ops {
  void *(* alloc) (void *alloc_ctx, unsigned long size,enum dma_data_direction dma_dir,gfp_t gfp_flags);
  void (* put) (void *buf_priv);
  struct dma_buf *(* get_dmabuf) (void *buf_priv, unsigned long flags);
  void *(* get_userptr) (void *alloc_ctx, unsigned long vaddr,unsigned long size,enum dma_data_direction dma_dir);
  void (* put_userptr) (void *buf_priv);
  void (* prepare) (void *buf_priv);
  void (* finish) (void *buf_priv);
  void *(* attach_dmabuf) (void *alloc_ctx, struct dma_buf *dbuf,unsigned long size,enum dma_data_direction dma_dir);
  void (* detach_dmabuf) (void *buf_priv);
  int (* map_dmabuf) (void *buf_priv);
  void (* unmap_dmabuf) (void *buf_priv);
  void *(* vaddr) (void *buf_priv);
  void *(* cookie) (void *buf_priv);
  unsigned int	(* num_users) (void *buf_priv);
  int (* mmap) (void *buf_priv, struct vm_area_struct *vma);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>alloc</term>
      <listitem><para>
allocate video memory and, optionally, allocator private data,
return NULL on failure or a pointer to allocator private,
per-buffer data on success; the returned private structure
will then be passed as buf_priv argument to other ops in this
structure. Additional gfp_flags to use when allocating the
are also passed to this operation. These flags are from the
gfp_flags field of vb2_queue.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>put</term>
      <listitem><para>
inform the allocator that the buffer will no longer be used;
usually will result in the allocator freeing the buffer (if
no other users of this buffer are present); the buf_priv
argument is the allocator private per-buffer structure
previously returned from the alloc callback.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_dmabuf</term>
      <listitem><para>
acquire userspace memory for a hardware operation; used for
DMABUF memory types.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_userptr</term>
      <listitem><para>
acquire userspace memory for a hardware operation; used for
USERPTR memory types; vaddr is the address passed to the
videobuf layer when queuing a video buffer of USERPTR type;
should return an allocator private per-buffer structure
associated with the buffer on success, NULL on failure;
the returned private structure will then be passed as buf_priv
argument to other ops in this structure.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>put_userptr</term>
      <listitem><para>
inform the allocator that a USERPTR buffer will no longer
be used.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>prepare</term>
      <listitem><para>
called every time the buffer is passed from userspace to the
driver, useful for cache synchronisation, optional.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>finish</term>
      <listitem><para>
called every time the buffer is passed back from the driver
to the userspace, also optional.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>attach_dmabuf</term>
      <listitem><para>
attach a shared struct dma_buf for a hardware operation;
used for DMABUF memory types; alloc_ctx is the alloc context
dbuf is the shared dma_buf; returns NULL on failure;
allocator private per-buffer structure on success;
this needs to be used for further accesses to the buffer.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>detach_dmabuf</term>
      <listitem><para>
inform the exporter of the buffer that the current DMABUF
buffer is no longer used; the buf_priv argument is the
allocator private per-buffer structure previously returned
from the attach_dmabuf callback.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>map_dmabuf</term>
      <listitem><para>
request for access to the dmabuf from allocator; the allocator
of dmabuf is informed that this driver is going to use the
dmabuf.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>unmap_dmabuf</term>
      <listitem><para>
releases access control to the dmabuf - allocator is notified
that this driver is done using the dmabuf for now.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>vaddr</term>
      <listitem><para>
return a kernel virtual address to a given memory buffer
associated with the passed private structure or NULL if no
such mapping exists.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cookie</term>
      <listitem><para>
return allocator specific cookie for a given memory buffer
associated with the passed private structure or NULL if not
available.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_users</term>
      <listitem><para>
return the current number of users of a memory buffer;
return 1 if the videobuf layer (or actually the driver using
it) is the only user.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mmap</term>
      <listitem><para>
setup a userspace mapping for a given memory buffer under
the provided virtual memory region.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Required ops for USERPTR types</title>
<para>
   get_userptr, put_userptr.
</para>
</refsect1>
<refsect1>
<title>Required ops for MMAP types</title>
<para>
   alloc, put, num_users, mmap.
   Required ops for read/write access types: alloc, put, num_users, vaddr.
</para>
</refsect1>
<refsect1>
<title>Required ops for DMABUF types</title>
<para>
   attach_dmabuf, detach_dmabuf, map_dmabuf,
   unmap_dmabuf.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-vb2-plane">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct vb2_plane</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct vb2_plane</refname>
 <refpurpose>
     plane information
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct vb2_plane {
  void * mem_priv;
  struct dma_buf * dbuf;
  unsigned int dbuf_mapped;
  unsigned int bytesused;
  unsigned int length;
  union m;
  unsigned int data_offset;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>mem_priv</term>
      <listitem><para>
   private data with this plane
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dbuf</term>
      <listitem><para>
   dma_buf - shared buffer object
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dbuf_mapped</term>
      <listitem><para>
   flag to show whether dbuf is mapped or not
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bytesused</term>
      <listitem><para>
   number of bytes occupied by data in the plane (payload)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>length</term>
      <listitem><para>
   size of this plane (NOT the payload) in bytes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>m</term>
      <listitem><para>
   Union with memtype-specific data (<parameter>offset</parameter>, <parameter>userptr</parameter> or
   <parameter>fd</parameter>).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>data_offset</term>
      <listitem><para>
   offset in the plane to the start of data; usually 0,
   unless there is a header in front of the data
   Should contain enough information to be able to cover all the fields
   of struct v4l2_plane at videodev2.h
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-enum-vb2-io-modes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum vb2_io_modes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum vb2_io_modes</refname>
 <refpurpose>
     queue access methods
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum vb2_io_modes {
  VB2_MMAP,
  VB2_USERPTR,
  VB2_READ,
  VB2_WRITE,
  VB2_DMABUF
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>VB2_MMAP</term>
      <listitem><para>
   driver supports MMAP with streaming API
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VB2_USERPTR</term>
      <listitem><para>
   driver supports USERPTR with streaming API
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VB2_READ</term>
      <listitem><para>
   driver supports <function>read</function> style access
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VB2_WRITE</term>
      <listitem><para>
   driver supports <function>write</function> style access
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VB2_DMABUF</term>
      <listitem><para>
   driver supports DMABUF with streaming API
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-enum-vb2-buffer-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum vb2_buffer_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum vb2_buffer_state</refname>
 <refpurpose>
     current video buffer state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum vb2_buffer_state {
  VB2_BUF_STATE_DEQUEUED,
  VB2_BUF_STATE_PREPARING,
  VB2_BUF_STATE_PREPARED,
  VB2_BUF_STATE_QUEUED,
  VB2_BUF_STATE_REQUEUEING,
  VB2_BUF_STATE_ACTIVE,
  VB2_BUF_STATE_DONE,
  VB2_BUF_STATE_ERROR
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>VB2_BUF_STATE_DEQUEUED</term>
      <listitem><para>
   buffer under userspace control
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VB2_BUF_STATE_PREPARING</term>
      <listitem><para>
   buffer is being prepared in videobuf
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VB2_BUF_STATE_PREPARED</term>
      <listitem><para>
   buffer prepared in videobuf and by the driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VB2_BUF_STATE_QUEUED</term>
      <listitem><para>
   buffer queued in videobuf, but not in driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VB2_BUF_STATE_REQUEUEING</term>
      <listitem><para>
   re-queue a buffer to the driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VB2_BUF_STATE_ACTIVE</term>
      <listitem><para>
   buffer queued in driver and possibly used
   in a hardware operation
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VB2_BUF_STATE_DONE</term>
      <listitem><para>
   buffer returned from driver to videobuf, but
   not yet dequeued to userspace
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VB2_BUF_STATE_ERROR</term>
      <listitem><para>
   same as above, but the operation on the buffer
   has ended with an error, which will be reported
   to the userspace when it is dequeued
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-struct-vb2-buffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct vb2_buffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct vb2_buffer</refname>
 <refpurpose>
     represents a video buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct vb2_buffer {
  struct vb2_queue * vb2_queue;
  unsigned int index;
  unsigned int type;
  unsigned int memory;
  unsigned int num_planes;
  struct vb2_plane planes[VB2_MAX_PLANES];
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>vb2_queue</term>
      <listitem><para>
   the queue to which this driver belongs
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>index</term>
      <listitem><para>
   id number of the buffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type</term>
      <listitem><para>
   buffer type
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>memory</term>
      <listitem><para>
   the method, in which the actual data is passed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_planes</term>
      <listitem><para>
   number of planes in the buffer
   on an internal driver queue
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>planes[VB2_MAX_PLANES]</term>
      <listitem><para>
   private per-plane information; do not change
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-vb2-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct vb2_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct vb2_ops</refname>
 <refpurpose>
     driver-specific callbacks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct vb2_ops {
  int (* queue_setup) (struct vb2_queue *q, const void *parg,unsigned int *num_buffers, unsigned int *num_planes,unsigned int sizes[], void *alloc_ctxs[]);
  void (* wait_prepare) (struct vb2_queue *q);
  void (* wait_finish) (struct vb2_queue *q);
  int (* buf_init) (struct vb2_buffer *vb);
  int (* buf_prepare) (struct vb2_buffer *vb);
  void (* buf_finish) (struct vb2_buffer *vb);
  void (* buf_cleanup) (struct vb2_buffer *vb);
  int (* start_streaming) (struct vb2_queue *q, unsigned int count);
  void (* stop_streaming) (struct vb2_queue *q);
  void (* buf_queue) (struct vb2_buffer *vb);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>queue_setup</term>
      <listitem><para>
   called from VIDIOC_REQBUFS and VIDIOC_CREATE_BUFS
   handlers before memory allocation, or, if
   *num_planes != 0, after the allocation to verify a
   smaller number of buffers. Driver should return
   the required number of buffers in *num_buffers, the
   required number of planes per buffer in *num_planes; the
   size of each plane should be set in the sizes[] array
   and optional per-plane allocator specific context in the
   alloc_ctxs[] array. When called from VIDIOC_REQBUFS,
   fmt == NULL, the driver has to use the currently
   configured format and *num_buffers is the total number
   of buffers, that are being allocated. When called from
   VIDIOC_CREATE_BUFS, fmt != NULL and it describes the
   target frame format (if the format isn't valid the
   callback must return -EINVAL). In this case *num_buffers
   are being allocated additionally to q-&gt;num_buffers.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>wait_prepare</term>
      <listitem><para>
   release any locks taken while calling vb2 functions;
   it is called before an ioctl needs to wait for a new
   buffer to arrive; required to avoid a deadlock in
   blocking access type.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>wait_finish</term>
      <listitem><para>
   reacquire all locks released in the previous callback;
   required to continue operation after sleeping while
   waiting for a new buffer to arrive.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>buf_init</term>
      <listitem><para>
   called once after allocating a buffer (in MMAP case)
   or after acquiring a new USERPTR buffer; drivers may
   perform additional buffer-related initialization;
   initialization failure (return != 0) will prevent
   queue setup from completing successfully; optional.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>buf_prepare</term>
      <listitem><para>
   called every time the buffer is queued from userspace
   and from the VIDIOC_PREPARE_BUF ioctl; drivers may
   perform any initialization required before each
   hardware operation in this callback; drivers can
   access/modify the buffer here as it is still synced for
   the CPU; drivers that support VIDIOC_CREATE_BUFS must
   also validate the buffer size; if an error is returned,
   the buffer will not be queued in driver; optional.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>buf_finish</term>
      <listitem><para>
   called before every dequeue of the buffer back to
   userspace; the buffer is synced for the CPU, so drivers
   can access/modify the buffer contents; drivers may
   perform any operations required before userspace
   accesses the buffer; optional. The buffer state can be
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>buf_cleanup</term>
      <listitem><para>
   called once before the buffer is freed; drivers may
   perform any additional cleanup; optional.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start_streaming</term>
      <listitem><para>
   called once to enter 'streaming' state; the driver may
   receive buffers with <parameter>buf_queue</parameter> callback before
   <parameter>start_streaming</parameter> is called; the driver gets the number
   of already queued buffers in count parameter; driver
   can return an error if hardware fails, in that case all
   buffers that have been already given by the <parameter>buf_queue</parameter>
   callback are to be returned by the driver by calling
   <parameter>vb2_buffer_done</parameter>(VB2_BUF_STATE_QUEUED).
   If you need a minimum number of buffers before you can
   start streaming, then set <parameter>min_buffers_needed</parameter> in the
   vb2_queue structure. If that is non-zero then
   start_streaming won't be called until at least that
   many buffers have been queued up by userspace.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>stop_streaming</term>
      <listitem><para>
   called when 'streaming' state must be disabled; driver
   should stop any DMA transactions or wait until they
   finish and give back all buffers it got from <function>buf_queue</function>
   callback by calling <parameter>vb2_buffer_done</parameter>() with either
   VB2_BUF_STATE_DONE or VB2_BUF_STATE_ERROR; may use
   <function>vb2_wait_for_all_buffers</function> function
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>buf_queue</term>
      <listitem><para>
   passes buffer vb to the driver; driver may start
   hardware operation on this buffer; driver should give
   the buffer back by calling <function>vb2_buffer_done</function> function;
   it is allways called after calling STREAMON ioctl;
   might be called before start_streaming callback if user
   pre-queued buffers before calling STREAMON.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>one of the following</title>
<para>
   DONE and ERROR occur while
   streaming is in progress, and the PREPARED state occurs
   when the queue has been canceled and all pending
   buffers are being returned to their default DEQUEUED
   state. Typically you only have to do something if the
   state is VB2_BUF_STATE_DONE, since in all other cases
   the buffer contents will be ignored anyway.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-vb2-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct vb2_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct vb2_queue</refname>
 <refpurpose>
     a videobuf queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct vb2_queue {
  unsigned int type;
  unsigned int io_modes;
  unsigned fileio_read_once:1;
  unsigned fileio_write_immediately:1;
  unsigned allow_zero_bytesused:1;
  struct mutex * lock;
  void * owner;
  const struct vb2_ops * ops;
  const struct vb2_mem_ops * mem_ops;
  const struct vb2_buf_ops * buf_ops;
  void * drv_priv;
  unsigned int buf_struct_size;
  u32 timestamp_flags;
  gfp_t gfp_flags;
  u32 min_buffers_needed;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>type</term>
      <listitem><para>
   private buffer type whose content is defined by the vb2-core
   caller. For example, for V4L2, it should match
   the V4L2_BUF_TYPE_* in include/uapi/linux/videodev2.h
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>io_modes</term>
      <listitem><para>
   supported io methods (see vb2_io_modes enum)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fileio_read_once</term>
      <listitem><para>
   report EOF after reading the first buffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fileio_write_immediately</term>
      <listitem><para>
   queue buffer after each <function>write</function> call
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>allow_zero_bytesused</term>
      <listitem><para>
   allow bytesused == 0 to be passed to the driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
   pointer to a mutex that protects the vb2_queue struct. The
   driver can set this to a mutex to let the v4l2 core serialize
   the queuing ioctls. If the driver wants to handle locking
   itself, then this should be set to NULL. This lock is not used
   by the videobuf2 core API.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>owner</term>
      <listitem><para>
   The filehandle that 'owns' the buffers, i.e. the filehandle
   that called reqbufs, create_buffers or started fileio.
   This field is not used by the videobuf2 core API, but it allows
   drivers to easily associate an owner filehandle with the queue.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ops</term>
      <listitem><para>
   driver-specific callbacks
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mem_ops</term>
      <listitem><para>
   memory allocator specific callbacks
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>buf_ops</term>
      <listitem><para>
   callbacks to deliver buffer information
   between user-space and kernel-space
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>drv_priv</term>
      <listitem><para>
   driver private data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>buf_struct_size</term>
      <listitem><para>
   size of the driver-specific buffer structure;
   <quote>0</quote> indicates the driver doesn't want to use a custom buffer
   structure type. for example, sizeof(struct vb2_v4l2_buffer)
   will be used for v4l2.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>timestamp_flags</term>
      <listitem><para>
   Timestamp flags; V4L2_BUF_FLAG_TIMESTAMP_* and
   V4L2_BUF_FLAG_TSTAMP_SRC_*
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>gfp_flags</term>
      <listitem><para>
   additional gfp flags used when allocating the buffers.
   Typically this is 0, but it may be e.g. GFP_DMA or __GFP_DMA32
   to force the buffer allocation to a specific memory zone.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>min_buffers_needed</term>
      <listitem><para>
   the minimum number of buffers needed before
   <function>start_streaming</function> can be called. Used when a DMA engine
   cannot be started unless at least this number of buffers
   have been queued into the driver.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-vb2-is-streaming">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vb2_is_streaming</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vb2_is_streaming</refname>
 <refpurpose>
     return streaming status of the queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>vb2_is_streaming </function></funcdef>
   <paramdef><link linkend="API-struct-vb2-queue">struct vb2_queue</link> * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     videobuf queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-vb2-fileio-is-active">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vb2_fileio_is_active</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vb2_fileio_is_active</refname>
 <refpurpose>
     return true if fileio is active.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>vb2_fileio_is_active </function></funcdef>
   <paramdef><link linkend="API-struct-vb2-queue">struct vb2_queue</link> * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     videobuf queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns true if <function>read</function> or <function>write</function> is used to stream the data
   as opposed to stream I/O. This is almost never an important distinction,
   except in rare cases. One such case is that using <function>read</function> or <function>write</function> to
   stream a format using V4L2_FIELD_ALTERNATE is not allowed since there
   is no way you can pass the field information of each buffer to/from
   userspace. A driver that supports this field format should check for
   this in the queue_setup op and reject it if this function returns true.
</para>
</refsect1>
</refentry>

<refentry id="API-vb2-is-busy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vb2_is_busy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vb2_is_busy</refname>
 <refpurpose>
     return busy status of the queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>vb2_is_busy </function></funcdef>
   <paramdef><link linkend="API-struct-vb2-queue">struct vb2_queue</link> * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     videobuf queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function checks if queue has any buffers allocated.
</para>
</refsect1>
</refentry>

<refentry id="API-vb2-get-drv-priv">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vb2_get_drv_priv</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vb2_get_drv_priv</refname>
 <refpurpose>
     return driver private data associated with the queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>vb2_get_drv_priv </function></funcdef>
   <paramdef><link linkend="API-struct-vb2-queue">struct vb2_queue</link> * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     videobuf queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-vb2-set-plane-payload">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vb2_set_plane_payload</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vb2_set_plane_payload</refname>
 <refpurpose>
     set bytesused for the plane plane_no
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>vb2_set_plane_payload </function></funcdef>
   <paramdef><link linkend="API-struct-vb2-buffer">struct vb2_buffer</link> * <parameter>vb</parameter></paramdef>
   <paramdef>unsigned int <parameter>plane_no</parameter></paramdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vb</parameter></term>
   <listitem>
    <para>
     buffer for which plane payload should be set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>plane_no</parameter></term>
   <listitem>
    <para>
     plane number for which payload should be set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     payload in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-vb2-get-plane-payload">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vb2_get_plane_payload</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vb2_get_plane_payload</refname>
 <refpurpose>
     get bytesused for the plane plane_no
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>vb2_get_plane_payload </function></funcdef>
   <paramdef><link linkend="API-struct-vb2-buffer">struct vb2_buffer</link> * <parameter>vb</parameter></paramdef>
   <paramdef>unsigned int <parameter>plane_no</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vb</parameter></term>
   <listitem>
    <para>
     buffer for which plane payload should be set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>plane_no</parameter></term>
   <listitem>
    <para>
     plane number for which payload should be set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-vb2-plane-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vb2_plane_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vb2_plane_size</refname>
 <refpurpose>
     return plane size in bytes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>vb2_plane_size </function></funcdef>
   <paramdef><link linkend="API-struct-vb2-buffer">struct vb2_buffer</link> * <parameter>vb</parameter></paramdef>
   <paramdef>unsigned int <parameter>plane_no</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vb</parameter></term>
   <listitem>
    <para>
     buffer for which plane size should be returned
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>plane_no</parameter></term>
   <listitem>
    <para>
     plane number for which size should be returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-vb2-start-streaming-called">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vb2_start_streaming_called</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vb2_start_streaming_called</refname>
 <refpurpose>
     return streaming status of driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>vb2_start_streaming_called </function></funcdef>
   <paramdef><link linkend="API-struct-vb2-queue">struct vb2_queue</link> * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     videobuf queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-vb2-clear-last-buffer-dequeued">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vb2_clear_last_buffer_dequeued</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vb2_clear_last_buffer_dequeued</refname>
 <refpurpose>
     clear last buffer dequeued flag of queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>vb2_clear_last_buffer_dequeued </function></funcdef>
   <paramdef><link linkend="API-struct-vb2-queue">struct vb2_queue</link> * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     videobuf queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- include/media/videobuf2-v4l2.h -->
<refentry id="API-struct-vb2-v4l2-buffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct vb2_v4l2_buffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct vb2_v4l2_buffer</refname>
 <refpurpose>
  video buffer information for v4l2
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct vb2_v4l2_buffer {
  struct vb2_buffer vb2_buf;
  __u32 flags;
  __u32 field;
  struct timeval timestamp;
  struct v4l2_timecode timecode;
  __u32 sequence;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>vb2_buf</term>
      <listitem><para>
video buffer 2
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
buffer informational flags
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>field</term>
      <listitem><para>
enum v4l2_field; field order of the image in the buffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>timestamp</term>
      <listitem><para>
frame timestamp
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>timecode</term>
      <listitem><para>
frame timecode
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sequence</term>
      <listitem><para>
sequence count of this frame
Should contain enough information to be able to cover all the fields
of struct v4l2_buffer at videodev2.h
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-vb2-thread-start">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vb2_thread_start</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vb2_thread_start</refname>
 <refpurpose>
     start a thread for the given queue.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vb2_thread_start </function></funcdef>
   <paramdef><link linkend="API-struct-vb2-queue">struct vb2_queue</link> * <parameter>q</parameter></paramdef>
   <paramdef>vb2_thread_fnc <parameter>fnc</parameter></paramdef>
   <paramdef>void * <parameter>priv</parameter></paramdef>
   <paramdef>const char * <parameter>thread_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     videobuf queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fnc</parameter></term>
   <listitem>
    <para>
     callback function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>priv</parameter></term>
   <listitem>
    <para>
     priv pointer passed to the callback function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>thread_name</parameter></term>
   <listitem>
    <para>
     the name of the thread. This will be prefixed with <quote>vb2-</quote>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This starts a thread that will queue and dequeue until an error occurs
   or <parameter>vb2_thread_stop</parameter> is called.
   </para><para>

   This function should not be used for anything else but the videobuf2-dvb
   support. If you think you have another good use-case for this, then please
   contact the linux-media mailinglist first.
</para>
</refsect1>
</refentry>

<refentry id="API-vb2-thread-stop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vb2_thread_stop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vb2_thread_stop</refname>
 <refpurpose>
     stop the thread for the given queue.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vb2_thread_stop </function></funcdef>
   <paramdef><link linkend="API-struct-vb2-queue">struct vb2_queue</link> * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     videobuf queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- include/media/videobuf2-memops.h -->
<refentry id="API-struct-vb2-vmarea-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct vb2_vmarea_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct vb2_vmarea_handler</refname>
 <refpurpose>
  common vma refcount tracking handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct vb2_vmarea_handler {
  atomic_t * refcount;
  void (* put) (void *arg);
  void * arg;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>refcount</term>
      <listitem><para>
pointer to refcount entry in the buffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>put</term>
      <listitem><para>
callback to function that decreases buffer refcount
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>arg</term>
      <listitem><para>
argument for <parameter>put</parameter> callback
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

     </sect1>
     <sect1><title>Digital TV (DVB) devices</title>
<!-- drivers/media/dvb-core/dvb_ca_en50221.h -->
<refentry id="API-struct-dvb-ca-en50221">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dvb_ca_en50221</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dvb_ca_en50221</refname>
 <refpurpose>
  Structure describing a CA interface
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dvb_ca_en50221 {
  struct module * owner;
  int (* read_attribute_mem) (struct dvb_ca_en50221 *ca,int slot, int address);
  int (* write_attribute_mem) (struct dvb_ca_en50221 *ca,int slot, int address, u8 value);
  int (* read_cam_control) (struct dvb_ca_en50221 *ca,int slot, u8 address);
  int (* write_cam_control) (struct dvb_ca_en50221 *ca,int slot, u8 address, u8 value);
  int (* slot_reset) (struct dvb_ca_en50221 *ca, int slot);
  int (* slot_shutdown) (struct dvb_ca_en50221 *ca, int slot);
  int (* slot_ts_enable) (struct dvb_ca_en50221 *ca, int slot);
  int (* poll_slot_status) (struct dvb_ca_en50221 *ca, int slot, int open);
  void * data;
  void * private;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>owner</term>
      <listitem><para>
the module owning this structure
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>read_attribute_mem</term>
      <listitem><para>
function for reading attribute memory on the CAM
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>write_attribute_mem</term>
      <listitem><para>
function for writing attribute memory on the CAM
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>read_cam_control</term>
      <listitem><para>
function for reading the control interface on the CAM
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>write_cam_control</term>
      <listitem><para>
function for reading the control interface on the CAM
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>slot_reset</term>
      <listitem><para>
function to reset the CAM slot
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>slot_shutdown</term>
      <listitem><para>
function to shutdown a CAM slot
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>slot_ts_enable</term>
      <listitem><para>
function to enable the Transport Stream on a CAM slot
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>poll_slot_status</term>
      <listitem><para>
function to poll slot status. Only necessary if
DVB_CA_FLAG_EN50221_IRQ_CAMCHANGE is not set.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>data</term>
      <listitem><para>
private data, used by caller.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>private</term>
      <listitem><para>
Opaque data used by the dvb_ca core. Do not modify!
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>NOTE</title>
<para>
   the read_*, write_* and poll_slot_status functions will be
   called for different slots concurrently and need to use locks where
   and if appropriate. There will be no concurrent access to one slot.
</para>
</refsect1>
</refentry>

<refentry id="API-dvb-ca-en50221-camchange-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_ca_en50221_camchange_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_ca_en50221_camchange_irq</refname>
 <refpurpose>
     A CAMCHANGE IRQ has occurred.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dvb_ca_en50221_camchange_irq </function></funcdef>
   <paramdef><link linkend="API-struct-dvb-ca-en50221">struct dvb_ca_en50221</link> * <parameter>pubca</parameter></paramdef>
   <paramdef>int <parameter>slot</parameter></paramdef>
   <paramdef>int <parameter>change_type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pubca</parameter></term>
   <listitem>
    <para>
     CA instance.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>slot</parameter></term>
   <listitem>
    <para>
     Slot concerned.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>change_type</parameter></term>
   <listitem>
    <para>
     One of the DVB_CA_CAMCHANGE_* values
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dvb-ca-en50221-camready-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_ca_en50221_camready_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_ca_en50221_camready_irq</refname>
 <refpurpose>
     A CAMREADY IRQ has occurred.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dvb_ca_en50221_camready_irq </function></funcdef>
   <paramdef><link linkend="API-struct-dvb-ca-en50221">struct dvb_ca_en50221</link> * <parameter>pubca</parameter></paramdef>
   <paramdef>int <parameter>slot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pubca</parameter></term>
   <listitem>
    <para>
     CA instance.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>slot</parameter></term>
   <listitem>
    <para>
     Slot concerned.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dvb-ca-en50221-frda-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_ca_en50221_frda_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_ca_en50221_frda_irq</refname>
 <refpurpose>
     An FR or a DA IRQ has occurred.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dvb_ca_en50221_frda_irq </function></funcdef>
   <paramdef><link linkend="API-struct-dvb-ca-en50221">struct dvb_ca_en50221</link> * <parameter>ca</parameter></paramdef>
   <paramdef>int <parameter>slot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ca</parameter></term>
   <listitem>
    <para>
     CA instance.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>slot</parameter></term>
   <listitem>
    <para>
     Slot concerned.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dvb-ca-en50221-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_ca_en50221_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_ca_en50221_init</refname>
 <refpurpose>
     Initialise a new DVB CA device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dvb_ca_en50221_init </function></funcdef>
   <paramdef><link linkend="API-struct-dvb-adapter">struct dvb_adapter</link> * <parameter>dvb_adapter</parameter></paramdef>
   <paramdef><link linkend="API-struct-dvb-ca-en50221">struct dvb_ca_en50221</link> * <parameter>ca</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
   <paramdef>int <parameter>slot_count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dvb_adapter</parameter></term>
   <listitem>
    <para>
     DVB adapter to attach the new CA device to.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ca</parameter></term>
   <listitem>
    <para>
     The dvb_ca instance.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     Flags describing the CA device (DVB_CA_EN50221_FLAG_*).
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>slot_count</parameter></term>
   <listitem>
    <para>
     Number of slots supported.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <parameter>return</parameter> 0 on success, nonzero on failure
</para>
</refsect1>
</refentry>

<refentry id="API-dvb-ca-en50221-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_ca_en50221_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_ca_en50221_release</refname>
 <refpurpose>
     Release a DVB CA device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dvb_ca_en50221_release </function></funcdef>
   <paramdef><link linkend="API-struct-dvb-ca-en50221">struct dvb_ca_en50221</link> * <parameter>ca</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ca</parameter></term>
   <listitem>
    <para>
     The associated dvb_ca instance.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/media/dvb-core/dvb_frontend.h -->
<refentry id="API-struct-dvb-frontend-tune-settings">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dvb_frontend_tune_settings</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dvb_frontend_tune_settings</refname>
 <refpurpose>
  parameters to adjust frontend tuning
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dvb_frontend_tune_settings {
  int min_delay_ms;
  int step_size;
  int max_drift;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>min_delay_ms</term>
      <listitem><para>
minimum delay for tuning, in ms
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>step_size</term>
      <listitem><para>
step size between two consecutive frequencies
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_drift</term>
      <listitem><para>
maximum drift
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>NOTE</title>
<para>
   step_size is in Hz, for terrestrial/cable or kHz for satellite
</para>
</refsect1>
</refentry>

<refentry id="API-struct-dvb-tuner-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dvb_tuner_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dvb_tuner_info</refname>
 <refpurpose>
     Frontend name and min/max ranges/bandwidths
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dvb_tuner_info {
  char name[128];
  u32 frequency_min;
  u32 frequency_max;
  u32 frequency_step;
  u32 bandwidth_min;
  u32 bandwidth_max;
  u32 bandwidth_step;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name[128]</term>
      <listitem><para>
   name of the Frontend
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>frequency_min</term>
      <listitem><para>
   minimal frequency supported
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>frequency_max</term>
      <listitem><para>
   maximum frequency supported
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>frequency_step</term>
      <listitem><para>
   frequency step
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bandwidth_min</term>
      <listitem><para>
   minimal frontend bandwidth supported
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bandwidth_max</term>
      <listitem><para>
   maximum frontend bandwidth supported
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bandwidth_step</term>
      <listitem><para>
   frontend bandwidth step
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>NOTE</title>
<para>
   frequency parameters are in Hz, for terrestrial/cable or kHz for
   satellite.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-analog-parameters">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct analog_parameters</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct analog_parameters</refname>
 <refpurpose>
     Parameters to tune into an analog/radio channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct analog_parameters {
  unsigned int frequency;
  unsigned int mode;
  unsigned int audmode;
  u64 std;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>frequency</term>
      <listitem><para>
   Frequency used by analog TV tuner (either in 62.5 kHz step,
   for TV, or 62.5 Hz for radio)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode</term>
      <listitem><para>
   Tuner mode, as defined on enum v4l2_tuner_type
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>audmode</term>
      <listitem><para>
   Audio mode as defined for the rxsubchans field at videodev2.h,
   e. g. V4L2_TUNER_MODE_*
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>std</term>
      <listitem><para>
   TV standard bitmap as defined at videodev2.h, e. g. V4L2_STD_*
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Hybrid tuners should be supported by both V4L2 and DVB APIs. This
   struct contains the data that are used by the V4L2 side. To avoid
   dependencies from V4L2 headers, all enums here are declared as integers.
</para>
</refsect1>
</refentry>

<refentry id="API-enum-dvbfe-algo">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum dvbfe_algo</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum dvbfe_algo</refname>
 <refpurpose>
     defines the algorithm used to tune into a channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum dvbfe_algo {
  DVBFE_ALGO_HW,
  DVBFE_ALGO_SW,
  DVBFE_ALGO_CUSTOM,
  DVBFE_ALGO_RECOVERY
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>DVBFE_ALGO_HW</term>
      <listitem><para>
   Hardware Algorithm -
   Devices that support this algorithm do everything in hardware
   and no software support is needed to handle them.
   Requesting these devices to LOCK is the only thing required,
   device is supposed to do everything in the hardware.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>DVBFE_ALGO_SW</term>
      <listitem><para>
   Software Algorithm -
   These are dumb devices, that require software to do everything
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>DVBFE_ALGO_CUSTOM</term>
      <listitem><para>
   Customizable Agorithm -
   Devices having this algorithm can be customized to have specific
   algorithms in the frontend driver, rather than simply doing a
   software zig-zag. In this case the zigzag maybe hardware assisted
   or it maybe completely done in hardware. In all cases, usage of
   this algorithm, in conjunction with the search and track
   callbacks, utilizes the driver specific algorithm.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>DVBFE_ALGO_RECOVERY</term>
      <listitem><para>
   Recovery Algorithm -
   These devices have AUTO recovery capabilities from LOCK failure
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-enum-dvbfe-search">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum dvbfe_search</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum dvbfe_search</refname>
 <refpurpose>
     search callback possible return status
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum dvbfe_search {
  DVBFE_ALGO_SEARCH_SUCCESS,
  DVBFE_ALGO_SEARCH_ASLEEP,
  DVBFE_ALGO_SEARCH_FAILED,
  DVBFE_ALGO_SEARCH_INVALID,
  DVBFE_ALGO_SEARCH_AGAIN,
  DVBFE_ALGO_SEARCH_ERROR
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>DVBFE_ALGO_SEARCH_SUCCESS</term>
      <listitem><para>
   The frontend search algorithm completed and returned successfully
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>DVBFE_ALGO_SEARCH_ASLEEP</term>
      <listitem><para>
   The frontend search algorithm is sleeping
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>DVBFE_ALGO_SEARCH_FAILED</term>
      <listitem><para>
   The frontend search for a signal failed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>DVBFE_ALGO_SEARCH_INVALID</term>
      <listitem><para>
   The frontend search algorith was probably supplied with invalid
   parameters and the search is an invalid one
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>DVBFE_ALGO_SEARCH_AGAIN</term>
      <listitem><para>
   The frontend search algorithm was requested to search again
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>DVBFE_ALGO_SEARCH_ERROR</term>
      <listitem><para>
   The frontend search algorithm failed due to some error
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-struct-dvb-tuner-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dvb_tuner_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dvb_tuner_ops</refname>
 <refpurpose>
     Tuner information and callbacks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dvb_tuner_ops {
  struct dvb_tuner_info info;
  int (* release) (struct dvb_frontend *fe);
  int (* init) (struct dvb_frontend *fe);
  int (* sleep) (struct dvb_frontend *fe);
  int (* suspend) (struct dvb_frontend *fe);
  int (* resume) (struct dvb_frontend *fe);
  int (* set_params) (struct dvb_frontend *fe);
  int (* set_analog_params) (struct dvb_frontend *fe, struct analog_parameters *p);
  int (* calc_regs) (struct dvb_frontend *fe, u8 *buf, int buf_len);
  int (* set_config) (struct dvb_frontend *fe, void *priv_cfg);
  int (* get_frequency) (struct dvb_frontend *fe, u32 *frequency);
  int (* get_bandwidth) (struct dvb_frontend *fe, u32 *bandwidth);
  int (* get_if_frequency) (struct dvb_frontend *fe, u32 *frequency);
#define TUNER_STATUS_LOCKED 1
#define TUNER_STATUS_STEREO 2
  int (* get_status) (struct dvb_frontend *fe, u32 *status);
  int (* get_rf_strength) (struct dvb_frontend *fe, u16 *strength);
  int (* get_afc) (struct dvb_frontend *fe, s32 *afc);
  int (* set_frequency) (struct dvb_frontend *fe, u32 frequency);
  int (* set_bandwidth) (struct dvb_frontend *fe, u32 bandwidth);
  int (* set_state) (struct dvb_frontend *fe, enum tuner_param param, struct tuner_state *state);
  int (* get_state) (struct dvb_frontend *fe, enum tuner_param param, struct tuner_state *state);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>info</term>
      <listitem><para>
   embedded struct dvb_tuner_info with tuner properties
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release</term>
      <listitem><para>
   callback function called when frontend is dettached.
   drivers should free any allocated memory.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>init</term>
      <listitem><para>
   callback function used to initialize the tuner device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sleep</term>
      <listitem><para>
   callback function used to put the tuner to sleep.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>suspend</term>
      <listitem><para>
   callback function used to inform that the Kernel will
   suspend.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>resume</term>
      <listitem><para>
   callback function used to inform that the Kernel is
   resuming from suspend.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_params</term>
      <listitem><para>
   callback function used to inform the tuner to tune
   into a digital TV channel. The properties to be used
   are stored at <parameter>dvb_frontend</parameter>.dtv_property_cache;. The
   tuner demod can change the parameters to reflect the
   changes needed for the channel to be tuned, and
   update statistics.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_analog_params</term>
      <listitem><para>
   callback function used to tune into an analog TV
   channel on hybrid tuners. It passes <parameter>analog_parameters</parameter>;
   to the driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>calc_regs</term>
      <listitem><para>
   callback function used to pass register data settings
   for simple tuners.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_config</term>
      <listitem><para>
   callback function used to send some tuner-specific
   parameters.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_frequency</term>
      <listitem><para>
   get the actual tuned frequency
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_bandwidth</term>
      <listitem><para>
   get the bandwitdh used by the low pass filters
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_if_frequency</term>
      <listitem><para>
   get the Intermediate Frequency, in Hz. For baseband,
   should return 0.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_status</term>
      <listitem><para>
   returns the frontend lock status
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_rf_strength</term>
      <listitem><para>
   returns the RF signal strengh. Used mostly to support
   analog TV and radio. Digital TV should report, instead,
   via DVBv5 API (<parameter>dvb_frontend</parameter>.dtv_property_cache;).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_afc</term>
      <listitem><para>
   Used only by analog TV core. Reports the frequency
   drift due to AFC.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_frequency</term>
      <listitem><para>
   Set a new frequency. Please notice that using
   set_params is preferred.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_bandwidth</term>
      <listitem><para>
   Set a new frequency. Please notice that using
   set_params is preferred.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_state</term>
      <listitem><para>
   callback function used on some legacy drivers that
   don't implement set_params in order to set properties.
   Shouldn't be used on new drivers.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_state</term>
      <listitem><para>
   callback function used to get properties by some
   legacy drivers that don't implement set_params.
   Shouldn't be used on new drivers.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>NOTE</title>
<para>
   frequencies used on get_frequency and set_frequency are in Hz for
   terrestrial/cable or kHz for satellite.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-analog-demod-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct analog_demod_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct analog_demod_info</refname>
 <refpurpose>
     Information struct for analog TV part of the demod
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct analog_demod_info {
  char * name;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name</term>
      <listitem><para>
   Name of the analog TV demodulator
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-analog-demod-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct analog_demod_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct analog_demod_ops</refname>
 <refpurpose>
     Demodulation information and callbacks for analog TV and radio
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct analog_demod_ops {
  struct analog_demod_info info;
  void (* set_params) (struct dvb_frontend *fe,struct analog_parameters *params);
  int (* has_signal) (struct dvb_frontend *fe, u16 *signal);
  int (* get_afc) (struct dvb_frontend *fe, s32 *afc);
  void (* tuner_status) (struct dvb_frontend *fe);
  void (* standby) (struct dvb_frontend *fe);
  void (* release) (struct dvb_frontend *fe);
  int (* i2c_gate_ctrl) (struct dvb_frontend *fe, int enable);
  int (* set_config) (struct dvb_frontend *fe, void *priv_cfg);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>info</term>
      <listitem><para>
   pointer to struct analog_demod_info
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_params</term>
      <listitem><para>
   callback function used to inform the demod to set the
   demodulator parameters needed to decode an analog or
   radio channel. The properties are passed via
   struct <parameter>analog_params</parameter>;.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>has_signal</term>
      <listitem><para>
   returns 0xffff if has signal, or 0 if it doesn't.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_afc</term>
      <listitem><para>
   Used only by analog TV core. Reports the frequency
   drift due to AFC.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tuner_status</term>
      <listitem><para>
   callback function that returns tuner status bits, e. g.
   TUNER_STATUS_LOCKED and TUNER_STATUS_STEREO.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>standby</term>
      <listitem><para>
   set the tuner to standby mode.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release</term>
      <listitem><para>
   callback function called when frontend is dettached.
   drivers should free any allocated memory.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>i2c_gate_ctrl</term>
      <listitem><para>
   controls the I2C gate. Newer drivers should use I2C
   mux support instead.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_config</term>
      <listitem><para>
   callback function used to send some tuner-specific
   parameters.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-dvb-frontend-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dvb_frontend_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dvb_frontend_ops</refname>
 <refpurpose>
     Demodulation information and callbacks for ditialt TV
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dvb_frontend_ops {
  struct dvb_frontend_info info;
  u8 delsys[MAX_DELSYS];
  void (* release) (struct dvb_frontend* fe);
  void (* release_sec) (struct dvb_frontend* fe);
  int (* init) (struct dvb_frontend* fe);
  int (* sleep) (struct dvb_frontend* fe);
  int (* write) (struct dvb_frontend* fe, const u8 buf[], int len);
  int (* tune) (struct dvb_frontend* fe,bool re_tune,unsigned int mode_flags,unsigned int *delay,enum fe_status *status);
  enum dvbfe_algo (* get_frontend_algo) (struct dvb_frontend *fe);
  int (* set_frontend) (struct dvb_frontend *fe);
  int (* get_tune_settings) (struct dvb_frontend* fe, struct dvb_frontend_tune_settings* settings);
  int (* get_frontend) (struct dvb_frontend *fe);
  int (* read_status) (struct dvb_frontend *fe, enum fe_status *status);
  int (* read_ber) (struct dvb_frontend* fe, u32* ber);
  int (* read_signal_strength) (struct dvb_frontend* fe, u16* strength);
  int (* read_snr) (struct dvb_frontend* fe, u16* snr);
  int (* read_ucblocks) (struct dvb_frontend* fe, u32* ucblocks);
  int (* diseqc_reset_overload) (struct dvb_frontend* fe);
  int (* diseqc_send_master_cmd) (struct dvb_frontend* fe, struct dvb_diseqc_master_cmd* cmd);
  int (* diseqc_recv_slave_reply) (struct dvb_frontend* fe, struct dvb_diseqc_slave_reply* reply);
  int (* diseqc_send_burst) (struct dvb_frontend *fe,enum fe_sec_mini_cmd minicmd);
  int (* set_tone) (struct dvb_frontend *fe, enum fe_sec_tone_mode tone);
  int (* set_voltage) (struct dvb_frontend *fe,enum fe_sec_voltage voltage);
  int (* enable_high_lnb_voltage) (struct dvb_frontend* fe, long arg);
  int (* dishnetwork_send_legacy_command) (struct dvb_frontend* fe, unsigned long cmd);
  int (* i2c_gate_ctrl) (struct dvb_frontend* fe, int enable);
  int (* ts_bus_ctrl) (struct dvb_frontend* fe, int acquire);
  int (* set_lna) (struct dvb_frontend *);
  enum dvbfe_search (* search) (struct dvb_frontend *fe);
  struct dvb_tuner_ops tuner_ops;
  struct analog_demod_ops analog_ops;
  int (* set_property) (struct dvb_frontend* fe, struct dtv_property* tvp);
  int (* get_property) (struct dvb_frontend* fe, struct dtv_property* tvp);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>info</term>
      <listitem><para>
   embedded struct dvb_tuner_info with tuner properties
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>delsys[MAX_DELSYS]</term>
      <listitem><para>
   Delivery systems supported by the frontend
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release</term>
      <listitem><para>
   callback function called when frontend is dettached.
   drivers should free any allocated memory.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release_sec</term>
      <listitem><para>
   callback function requesting that the Satelite Equipment
   Control (SEC) driver to release and free any memory
   allocated by the driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>init</term>
      <listitem><para>
   callback function used to initialize the tuner device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sleep</term>
      <listitem><para>
   callback function used to put the tuner to sleep.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>write</term>
      <listitem><para>
   callback function used by some demod legacy drivers to
   allow other drivers to write data into their registers.
   Should not be used on new drivers.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tune</term>
      <listitem><para>
   callback function used by demod drivers that use
   <parameter>DVBFE_ALGO_HW</parameter>; to tune into a frequency.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_frontend_algo</term>
      <listitem><para>
   returns the desired hardware algorithm.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_frontend</term>
      <listitem><para>
   callback function used to inform the demod to set the
   parameters for demodulating a digital TV channel.
   The properties to be used are stored at
   <parameter>dvb_frontend</parameter>.dtv_property_cache;. The demod can change
   the parameters to reflect the changes needed for the
   channel to be decoded, and update statistics.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_tune_settings</term>
      <listitem><para>
   callback function
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_frontend</term>
      <listitem><para>
   callback function used to inform the parameters
   actuall in use. The properties to be used are stored at
   <parameter>dvb_frontend</parameter>.dtv_property_cache; and update
   statistics. Please notice that it should not return
   an error code if the statistics are not available
   because the demog is not locked.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>read_status</term>
      <listitem><para>
   returns the locking status of the frontend.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>read_ber</term>
      <listitem><para>
   legacy callback function to return the bit error rate.
   Newer drivers should provide such info via DVBv5 API,
   e. g. <parameter>set_frontend</parameter>;/<parameter>get_frontend</parameter>;, implementing this
   callback only if DVBv3 API compatibility is wanted.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>read_signal_strength</term>
      <listitem><para>
   legacy callback function to return the signal
   strength. Newer drivers should provide such info via
   DVBv5 API, e. g. <parameter>set_frontend</parameter>;/<parameter>get_frontend</parameter>;,
   implementing this callback only if DVBv3 API
   compatibility is wanted.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>read_snr</term>
      <listitem><para>
   legacy callback function to return the Signal/Noise
   rate. Newer drivers should provide such info via
   DVBv5 API, e. g. <parameter>set_frontend</parameter>;/<parameter>get_frontend</parameter>;,
   implementing this callback only if DVBv3 API
   compatibility is wanted.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>read_ucblocks</term>
      <listitem><para>
   legacy callback function to return the Uncorrected Error
   Blocks. Newer drivers should provide such info via
   DVBv5 API, e. g. <parameter>set_frontend</parameter>;/<parameter>get_frontend</parameter>;,
   implementing this callback only if DVBv3 API
   compatibility is wanted.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>diseqc_reset_overload</term>
      <listitem><para>
   callback function to implement the
   FE_DISEQC_RESET_OVERLOAD ioctl (only Satellite)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>diseqc_send_master_cmd</term>
      <listitem><para>
   callback function to implement the
   FE_DISEQC_SEND_MASTER_CMD ioctl (only Satellite).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>diseqc_recv_slave_reply</term>
      <listitem><para>
   callback function to implement the
   FE_DISEQC_RECV_SLAVE_REPLY ioctl (only Satellite)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>diseqc_send_burst</term>
      <listitem><para>
   callback function to implement the
   FE_DISEQC_SEND_BURST ioctl (only Satellite).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_tone</term>
      <listitem><para>
   callback function to implement the
   FE_SET_TONE ioctl (only Satellite).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_voltage</term>
      <listitem><para>
   callback function to implement the
   FE_SET_VOLTAGE ioctl (only Satellite).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enable_high_lnb_voltage</term>
      <listitem><para>
   callback function to implement the
   FE_ENABLE_HIGH_LNB_VOLTAGE ioctl (only Satellite).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dishnetwork_send_legacy_command</term>
      <listitem><para>
   callback function to implement the
   FE_DISHNETWORK_SEND_LEGACY_CMD ioctl (only Satellite).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>i2c_gate_ctrl</term>
      <listitem><para>
   controls the I2C gate. Newer drivers should use I2C
   mux support instead.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ts_bus_ctrl</term>
      <listitem><para>
   callback function used to take control of the TS bus.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_lna</term>
      <listitem><para>
   callback function to power on/off/auto the LNA.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>search</term>
      <listitem><para>
   callback function used on some custom algo search algos.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tuner_ops</term>
      <listitem><para>
   pointer to struct dvb_tuner_ops
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>analog_ops</term>
      <listitem><para>
   pointer to struct analog_demod_ops
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_property</term>
      <listitem><para>
   callback function to allow the frontend to validade
   incoming properties. Should not be used on new drivers.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_property</term>
      <listitem><para>
   callback function to allow the frontend to override
   outcoming properties. Should not be used on new drivers.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-dtv-frontend-properties">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dtv_frontend_properties</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dtv_frontend_properties</refname>
 <refpurpose>
     contains a list of properties that are specific to a digital TV standard.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dtv_frontend_properties {
  u32 frequency;
  enum fe_modulation modulation;
  enum fe_sec_voltage voltage;
  enum fe_sec_tone_mode sectone;
  enum fe_spectral_inversion inversion;
  enum fe_code_rate fec_inner;
  enum fe_transmit_mode transmission_mode;
  u32 bandwidth_hz;
  enum fe_guard_interval guard_interval;
  enum fe_hierarchy hierarchy;
  u32 symbol_rate;
  enum fe_code_rate code_rate_HP;
  enum fe_code_rate code_rate_LP;
  enum fe_pilot pilot;
  enum fe_rolloff rolloff;
  enum fe_delivery_system delivery_system;
  enum fe_interleaving interleaving;
  u8 isdbt_partial_reception;
  u8 isdbt_sb_mode;
  u8 isdbt_sb_subchannel;
  u32 isdbt_sb_segment_idx;
  u32 isdbt_sb_segment_count;
  u8 isdbt_layer_enabled;
  struct layer[3];
  u32 stream_id;
  u8 atscmh_fic_ver;
  u8 atscmh_parade_id;
  u8 atscmh_nog;
  u8 atscmh_tnog;
  u8 atscmh_sgn;
  u8 atscmh_prc;
  u8 atscmh_rs_frame_mode;
  u8 atscmh_rs_frame_ensemble;
  u8 atscmh_rs_code_mode_pri;
  u8 atscmh_rs_code_mode_sec;
  u8 atscmh_sccc_block_mode;
  u8 atscmh_sccc_code_mode_a;
  u8 atscmh_sccc_code_mode_b;
  u8 atscmh_sccc_code_mode_c;
  u8 atscmh_sccc_code_mode_d;
  u32 lna;
  struct dtv_fe_stats strength;
  struct dtv_fe_stats cnr;
  struct dtv_fe_stats pre_bit_error;
  struct dtv_fe_stats pre_bit_count;
  struct dtv_fe_stats post_bit_error;
  struct dtv_fe_stats post_bit_count;
  struct dtv_fe_stats block_error;
  struct dtv_fe_stats block_count;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>frequency</term>
      <listitem><para>
   frequency in Hz for terrestrial/cable or in kHz for
   Satellite
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>modulation</term>
      <listitem><para>
   Frontend modulation type
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>voltage</term>
      <listitem><para>
   SEC voltage (only Satellite)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sectone</term>
      <listitem><para>
   SEC tone mode (only Satellite)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>inversion</term>
      <listitem><para>
   Spectral inversion
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fec_inner</term>
      <listitem><para>
   Forward error correction inner Code Rate
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transmission_mode</term>
      <listitem><para>
   Transmission Mode
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bandwidth_hz</term>
      <listitem><para>
   Bandwidth, in Hz. A zero value means that userspace
   wants to autodetect.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>guard_interval</term>
      <listitem><para>
   Guard Interval
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>hierarchy</term>
      <listitem><para>
   Hierarchy
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>symbol_rate</term>
      <listitem><para>
   Symbol Rate
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>code_rate_HP</term>
      <listitem><para>
   high priority stream code rate
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>code_rate_LP</term>
      <listitem><para>
   low priority stream code rate
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pilot</term>
      <listitem><para>
   Enable/disable/autodetect pilot tones
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rolloff</term>
      <listitem><para>
   Rolloff factor (alpha)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>delivery_system</term>
      <listitem><para>
   FE delivery system (e. g. digital TV standard)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>interleaving</term>
      <listitem><para>
   interleaving
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>isdbt_partial_reception</term>
      <listitem><para>
   ISDB-T partial reception (only ISDB standard)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>isdbt_sb_mode</term>
      <listitem><para>
   ISDB-T Sound Broadcast (SB) mode (only ISDB standard)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>isdbt_sb_subchannel</term>
      <listitem><para>
   ISDB-T SB subchannel (only ISDB standard)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>isdbt_sb_segment_idx</term>
      <listitem><para>
   ISDB-T SB segment index (only ISDB standard)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>isdbt_sb_segment_count</term>
      <listitem><para>
   ISDB-T SB segment count (only ISDB standard)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>isdbt_layer_enabled</term>
      <listitem><para>
   ISDB Layer enabled (only ISDB standard)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>layer[3]</term>
      <listitem><para>
   ISDB per-layer data (only ISDB standard)
   <parameter>layer</parameter>.segment_count: Segment Count;
   <parameter>layer</parameter>.fec:		per layer code rate;
   <parameter>layer</parameter>.modulation:	per layer modulation;
   <parameter>layer</parameter>.interleaving:	 per layer interleaving.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>stream_id</term>
      <listitem><para>
   If different than zero, enable substream filtering, if
   hardware supports (DVB-S2 and DVB-T2).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_fic_ver</term>
      <listitem><para>
   Version number of the FIC (Fast Information Channel)
   signaling data (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_parade_id</term>
      <listitem><para>
   Parade identification number (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_nog</term>
      <listitem><para>
   Number of MH groups per MH subframe for a designated
   parade (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_tnog</term>
      <listitem><para>
   Total number of MH groups including all MH groups
   belonging to all MH parades in one MH subframe
   (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_sgn</term>
      <listitem><para>
   Start group number (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_prc</term>
      <listitem><para>
   Parade repetition cycle (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_rs_frame_mode</term>
      <listitem><para>
   Reed Solomon (RS) frame mode (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_rs_frame_ensemble</term>
      <listitem><para>
   RS frame ensemble (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_rs_code_mode_pri</term>
      <listitem><para>
   RS code mode pri (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_rs_code_mode_sec</term>
      <listitem><para>
   RS code mode sec (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_sccc_block_mode</term>
      <listitem><para>
   Series Concatenated Convolutional Code (SCCC)
   Block Mode (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_sccc_code_mode_a</term>
      <listitem><para>
   SCCC code mode A (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_sccc_code_mode_b</term>
      <listitem><para>
   SCCC code mode B (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_sccc_code_mode_c</term>
      <listitem><para>
   SCCC code mode C (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atscmh_sccc_code_mode_d</term>
      <listitem><para>
   SCCC code mode D (only ATSC-M/H)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lna</term>
      <listitem><para>
   Power ON/OFF/AUTO the Linear Now-noise Amplifier (LNA)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>strength</term>
      <listitem><para>
   DVBv5 API statistics: Signal Strength
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cnr</term>
      <listitem><para>
   DVBv5 API statistics: Signal to Noise ratio of the
   (main) carrier
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pre_bit_error</term>
      <listitem><para>
   DVBv5 API statistics: pre-Viterbi bit error count
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pre_bit_count</term>
      <listitem><para>
   DVBv5 API statistics: pre-Viterbi bit count
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>post_bit_error</term>
      <listitem><para>
   DVBv5 API statistics: post-Viterbi bit error count
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>post_bit_count</term>
      <listitem><para>
   DVBv5 API statistics: post-Viterbi bit count
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>block_error</term>
      <listitem><para>
   DVBv5 API statistics: block error count
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>block_count</term>
      <listitem><para>
   DVBv5 API statistics: block count
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>NOTE</title>
<para>
   derivated statistics like Uncorrected Error blocks (UCE) are
   calculated on userspace.
   </para><para>

   Only a subset of the properties are needed for a given delivery system.
   For more info, consult the media_api.html with the documentation of the
   Userspace API.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-dvb-frontend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dvb_frontend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dvb_frontend</refname>
 <refpurpose>
     Frontend structure to be used on drivers.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dvb_frontend {
  struct dvb_frontend_ops ops;
  struct dvb_adapter * dvb;
  void * demodulator_priv;
  void * tuner_priv;
  void * frontend_priv;
  void * sec_priv;
  void * analog_demod_priv;
  struct dtv_frontend_properties dtv_property_cache;
#define DVB_FRONTEND_COMPONENT_TUNER 0
#define DVB_FRONTEND_COMPONENT_DEMOD 1
  int (* callback) (void *adapter_priv, int component, int cmd, int arg);
  int id;
  unsigned int exit;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>ops</term>
      <listitem><para>
   embedded struct dvb_frontend_ops
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dvb</term>
      <listitem><para>
   pointer to struct dvb_adapter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>demodulator_priv</term>
      <listitem><para>
   demod private data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tuner_priv</term>
      <listitem><para>
   tuner private data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>frontend_priv</term>
      <listitem><para>
   frontend private data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sec_priv</term>
      <listitem><para>
   SEC private data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>analog_demod_priv</term>
      <listitem><para>
   Analog demod private data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dtv_property_cache</term>
      <listitem><para>
   embedded struct dtv_frontend_properties
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>callback</term>
      <listitem><para>
   callback function used on some drivers to call
   either the tuner or the demodulator.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id</term>
      <listitem><para>
   Frontend ID
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>exit</term>
      <listitem><para>
   Used to inform the DVB core that the frontend
   thread should exit (usually, means that the hardware
   got disconnected.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- drivers/media/dvb-core/dvb_math.h -->
<refentry id="API-intlog2">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intlog2</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intlog2</refname>
 <refpurpose>
  computes log2 of a value; the result is shifted left by 24 bits
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>intlog2 </function></funcdef>
   <paramdef>u32 <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     The value (must be != 0)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>to use rational values you can use the following method</title>
<para>
   intlog2(value) = intlog2(value * 2^x) - x * 2^24
</para>
</refsect1>
<refsect1>
<title>Some usecase examples</title>
<informalexample><programlisting>
   	intlog2(8) will give 3 &lt;&lt; 24 = 3 * 2^24
   	intlog2(9) will give 3 &lt;&lt; 24 + ... = 3.16... * 2^24
   	intlog2(1.5) = intlog2(3) - 2^24 = 0.584... * 2^24
</programlisting></informalexample>
</refsect1>
<refsect1>
<title>return</title>
<para>
   log2(value) * 2^24
</para>
</refsect1>
</refentry>

<refentry id="API-intlog10">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intlog10</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intlog10</refname>
 <refpurpose>
     computes log10 of a value; the result is shifted left by 24 bits
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>intlog10 </function></funcdef>
   <paramdef>u32 <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     The value (must be != 0)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>to use rational values you can use the following method</title>
<para>
   intlog10(value) = intlog10(value * 10^x) - x * 2^24
</para>
</refsect1>
<refsect1>
<title>An usecase example</title>
<informalexample><programlisting>
   	intlog10(1000) will give 3 &lt;&lt; 24 = 3 * 2^24
     due to the implementation intlog10(1000) might be not exactly 3 * 2^24

   look at intlog2 for similar examples
</programlisting></informalexample>
</refsect1>
<refsect1>
<title>return</title>
<para>
   log10(value) * 2^24
</para>
</refsect1>
</refentry>

<!-- drivers/media/dvb-core/dvb_ringbuffer.h -->
<refentry id="API-dvb-ringbuffer-pkt-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_ringbuffer_pkt_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_ringbuffer_pkt_write</refname>
 <refpurpose>
  Write a packet into the ringbuffer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>dvb_ringbuffer_pkt_write </function></funcdef>
   <paramdef>struct dvb_ringbuffer * <parameter>rbuf</parameter></paramdef>
   <paramdef>u8 * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rbuf</parameter></term>
   <listitem>
    <para>
     Ringbuffer to write to.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     Buffer to write.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     Length of buffer (currently limited to 65535 bytes max).
     returns Number of bytes written, or -EFAULT, -ENOMEM, -EVINAL.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dvb-ringbuffer-pkt-read-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_ringbuffer_pkt_read_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_ringbuffer_pkt_read_user</refname>
 <refpurpose>
     Read from a packet in the ringbuffer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>dvb_ringbuffer_pkt_read_user </function></funcdef>
   <paramdef>struct dvb_ringbuffer * <parameter>rbuf</parameter></paramdef>
   <paramdef>size_t <parameter>idx</parameter></paramdef>
   <paramdef>int <parameter>offset</parameter></paramdef>
   <paramdef>u8 __user * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rbuf</parameter></term>
   <listitem>
    <para>
     Ringbuffer concerned.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>idx</parameter></term>
   <listitem>
    <para>
     Packet index as returned by <function><link linkend="API-dvb-ringbuffer-pkt-next">dvb_ringbuffer_pkt_next</link></function>.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     Offset into packet to read from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     Destination buffer for data.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     Size of destination buffer.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   unlike <function>dvb_ringbuffer_read</function>, this does NOT update the read pointer
   in the ringbuffer. You must use <function><link linkend="API-dvb-ringbuffer-pkt-dispose">dvb_ringbuffer_pkt_dispose</link></function> to mark a
   packet as no longer required.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   returns Number of bytes read, or -EFAULT.
</para>
</refsect1>
</refentry>

<refentry id="API-dvb-ringbuffer-pkt-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_ringbuffer_pkt_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_ringbuffer_pkt_read</refname>
 <refpurpose>
     Read from a packet in the ringbuffer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>dvb_ringbuffer_pkt_read </function></funcdef>
   <paramdef>struct dvb_ringbuffer * <parameter>rbuf</parameter></paramdef>
   <paramdef>size_t <parameter>idx</parameter></paramdef>
   <paramdef>int <parameter>offset</parameter></paramdef>
   <paramdef>u8 * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rbuf</parameter></term>
   <listitem>
    <para>
     Ringbuffer concerned.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>idx</parameter></term>
   <listitem>
    <para>
     Packet index as returned by <function><link linkend="API-dvb-ringbuffer-pkt-next">dvb_ringbuffer_pkt_next</link></function>.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     Offset into packet to read from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     Destination buffer for data.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     Size of destination buffer.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   unlike <function>dvb_ringbuffer_read_user</function>, this DOES update the read pointer
   in the ringbuffer.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   returns Number of bytes read, or -EFAULT.
</para>
</refsect1>
</refentry>

<refentry id="API-dvb-ringbuffer-pkt-dispose">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_ringbuffer_pkt_dispose</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_ringbuffer_pkt_dispose</refname>
 <refpurpose>
     Dispose of a packet in the ring buffer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dvb_ringbuffer_pkt_dispose </function></funcdef>
   <paramdef>struct dvb_ringbuffer * <parameter>rbuf</parameter></paramdef>
   <paramdef>size_t <parameter>idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rbuf</parameter></term>
   <listitem>
    <para>
     Ring buffer concerned.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>idx</parameter></term>
   <listitem>
    <para>
     Packet index as returned by <function><link linkend="API-dvb-ringbuffer-pkt-next">dvb_ringbuffer_pkt_next</link></function>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dvb-ringbuffer-pkt-next">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_ringbuffer_pkt_next</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_ringbuffer_pkt_next</refname>
 <refpurpose>
     Get the index of the next packet in a ringbuffer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>dvb_ringbuffer_pkt_next </function></funcdef>
   <paramdef>struct dvb_ringbuffer * <parameter>rbuf</parameter></paramdef>
   <paramdef>size_t <parameter>idx</parameter></paramdef>
   <paramdef>size_t * <parameter>pktlen</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rbuf</parameter></term>
   <listitem>
    <para>
     Ringbuffer concerned.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>idx</parameter></term>
   <listitem>
    <para>
     Previous packet index, or -1 to return the first packet index.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pktlen</parameter></term>
   <listitem>
    <para>
     On success, will be updated to contain the length of the packet in bytes.
     returns Packet index (if &gt;=0), or -1 if no packets available.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/media/dvb-core/dvbdev.h -->
<refentry id="API-struct-dvb-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dvb_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dvb_adapter</refname>
 <refpurpose>
  represents a Digital TV adapter using Linux DVB API
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dvb_adapter {
  int num;
  struct list_head list_head;
  struct list_head device_list;
  const char * name;
  u8 proposed_mac[6];
  void * priv;
  struct device * device;
  struct module * module;
  int mfe_shared;
  struct dvb_device * mfe_dvbdev;
  struct mutex mfe_lock;
#if defined(CONFIG_MEDIA_CONTROLLER_DVB)
  struct media_device * mdev;
#endif
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>num</term>
      <listitem><para>
Number of the adapter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>list_head</term>
      <listitem><para>
List with the DVB adapters
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>device_list</term>
      <listitem><para>
List with the DVB devices
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name</term>
      <listitem><para>
Name of the adapter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>proposed_mac[6]</term>
      <listitem><para>
proposed MAC address for the adapter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>priv</term>
      <listitem><para>
private data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>device</term>
      <listitem><para>
pointer to struct device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>module</term>
      <listitem><para>
pointer to struct module
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mfe_shared</term>
      <listitem><para>
mfe shared: indicates mutually exclusive frontends
Thie usage of this flag is currently deprecated
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mfe_dvbdev</term>
      <listitem><para>
Frontend device in use, in the case of MFE
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mfe_lock</term>
      <listitem><para>
Lock to prevent using the other frontends when MFE is
used.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mdev</term>
      <listitem><para>
pointer to struct media_device, used when the media
controller is used.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-dvb-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dvb_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dvb_device</refname>
 <refpurpose>
     represents a DVB device node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dvb_device {
  struct list_head list_head;
  const struct file_operations * fops;
  struct dvb_adapter * adapter;
  int type;
  int minor;
  u32 id;
  int readers;
  int writers;
  int users;
  wait_queue_head_t wait_queue;
  int (* kernel_ioctl) (struct file *file, unsigned int cmd, void *arg);
#if defined(CONFIG_MEDIA_CONTROLLER_DVB)
  const char * name;
  struct media_entity * entity;
  struct media_pad * pads;
#endif
  void * priv;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>list_head</term>
      <listitem><para>
   List head with all DVB devices
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fops</term>
      <listitem><para>
   pointer to struct file_operations
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>adapter</term>
      <listitem><para>
   pointer to the adapter that holds this device node
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type</term>
      <listitem><para>
   type of the device: DVB_DEVICE_SEC, DVB_DEVICE_FRONTEND,
   DVB_DEVICE_DEMUX, DVB_DEVICE_DVR, DVB_DEVICE_CA, DVB_DEVICE_NET
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>minor</term>
      <listitem><para>
   devnode minor number. Major number is always DVB_MAJOR.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id</term>
      <listitem><para>
   device ID number, inside the adapter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>readers</term>
      <listitem><para>
   Initialized by the caller. Each call to <function>open</function> in Read Only mode
   decreases this counter by one.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>writers</term>
      <listitem><para>
   Initialized by the caller. Each call to <function>open</function> in Read/Write
   mode decreases this counter by one.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>users</term>
      <listitem><para>
   Initialized by the caller. Each call to <function>open</function> in any mode
   decreases this counter by one.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>wait_queue</term>
      <listitem><para>
   wait queue, used to wait for certain events inside one of
   the DVB API callers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>kernel_ioctl</term>
      <listitem><para>
   callback function used to handle ioctl calls from userspace.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name</term>
      <listitem><para>
   Name to be used for the device at the Media Controller
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>entity</term>
      <listitem><para>
   pointer to struct media_entity associated with the device node
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pads</term>
      <listitem><para>
   pointer to struct media_pad associated with <parameter>entity</parameter>;
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>priv</term>
      <listitem><para>
   private data
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This structure is used by the DVB core (frontend, CA, net, demux) in
   order to create the device nodes. Usually, driver should not initialize
   this struct diretly.
</para>
</refsect1>
</refentry>

<refentry id="API-dvb-register-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_register_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_register_adapter</refname>
 <refpurpose>
     Registers a new DVB adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dvb_register_adapter </function></funcdef>
   <paramdef><link linkend="API-struct-dvb-adapter">struct dvb_adapter</link> * <parameter>adap</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct module * <parameter>module</parameter></paramdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>device</parameter></paramdef>
   <paramdef>short * <parameter>adapter_nums</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adap</parameter></term>
   <listitem>
    <para>
     pointer to struct dvb_adapter
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     Adapter's name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>module</parameter></term>
   <listitem>
    <para>
     initialized with THIS_MODULE at the caller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     pointer to struct device that corresponds to the device driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>adapter_nums</parameter></term>
   <listitem>
    <para>
     Array with a list of the numbers for <parameter>dvb_register_adapter</parameter>;
     to select among them. Typically, initialized with:
     DVB_DEFINE_MOD_OPT_ADAPTER_NR(adapter_nums)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dvb-unregister-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_unregister_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_unregister_adapter</refname>
 <refpurpose>
     Unregisters a DVB adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dvb_unregister_adapter </function></funcdef>
   <paramdef><link linkend="API-struct-dvb-adapter">struct dvb_adapter</link> * <parameter>adap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adap</parameter></term>
   <listitem>
    <para>
     pointer to struct dvb_adapter
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dvb-register-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_register_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_register_device</refname>
 <refpurpose>
     Registers a new DVB device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dvb_register_device </function></funcdef>
   <paramdef><link linkend="API-struct-dvb-adapter">struct dvb_adapter</link> * <parameter>adap</parameter></paramdef>
   <paramdef>struct dvb_device ** <parameter>pdvbdev</parameter></paramdef>
   <paramdef><link linkend="API-struct-dvb-device">const struct dvb_device</link> * <parameter>template</parameter></paramdef>
   <paramdef>void * <parameter>priv</parameter></paramdef>
   <paramdef>int <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adap</parameter></term>
   <listitem>
    <para>
     pointer to struct dvb_adapter
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pdvbdev</parameter></term>
   <listitem>
    <para>
     pointer to the place where the new struct dvb_device will be
     stored
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>template</parameter></term>
   <listitem>
    <para>
     Template used to create <structname>pdvbdev</structname>;
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>priv</parameter></term>
   <listitem>
    <para>
     private data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of the device: DVB_DEVICE_SEC, DVB_DEVICE_FRONTEND,
     DVB_DEVICE_DEMUX, DVB_DEVICE_DVR, DVB_DEVICE_CA, DVB_DEVICE_NET
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dvb-unregister-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dvb_unregister_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dvb_unregister_device</refname>
 <refpurpose>
     Unregisters a DVB device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dvb_unregister_device </function></funcdef>
   <paramdef><link linkend="API-struct-dvb-device">struct dvb_device</link> * <parameter>dvbdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dvbdev</parameter></term>
   <listitem>
    <para>
     pointer to struct dvb_device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

	<sect1><title>Digital TV Demux API</title>
	    <para>The kernel demux API defines a driver-internal interface for
	    registering low-level, hardware specific driver to a hardware
	    independent demux layer. It is only of interest for Digital TV
	    device driver writers. The header file for this API is named
	    <constant>demux.h</constant> and located in
	    <constant>drivers/media/dvb-core</constant>.</para>

	<para>The demux API should be implemented for each demux in the
	system. It is used to select the TS source of a demux and to manage
	the demux resources. When the demux client allocates a resource via
	the demux API, it receives a pointer to the API of that
	resource.</para>
	<para>Each demux receives its TS input from a DVB front-end or from
	memory, as set via this demux API. In a system with more than one
	front-end, the API can be used to select one of the DVB front-ends
	as a TS source for a demux, unless this is fixed in the HW platform.
	The demux API only controls front-ends regarding to their connections
	with demuxes; the APIs used to set the other front-end parameters,
	such as tuning, are not defined in this document.</para>
	<para>The functions that implement the abstract interface demux should
	be defined static or module private and registered to the Demux
	core for external access. It is not necessary to implement every
	function in the struct <constant>dmx_demux</constant>. For example,
	a demux interface might support Section filtering, but not PES
	filtering. The API client is expected to check the value of any
	function pointer before calling the function: the value of NULL means
	that the &#8220;function is not available&#8221;.</para>
	<para>Whenever the functions of the demux API modify shared data,
	the possibilities of lost update and race condition problems should
	be addressed, e.g. by protecting parts of code with mutexes.</para>
	<para>Note that functions called from a bottom half context must not
	sleep. Even a simple memory allocation without using GFP_ATOMIC can
	result in a kernel thread being put to sleep if swapping is needed.
	For example, the Linux kernel calls the functions of a network device
	interface from a bottom half context. Thus, if a demux API function
	is called from network device code, the function must not sleep.
	</para>
    </sect1>

    <section id="demux_callback_api">
	<title>Demux Callback API</title>
	<para>This kernel-space API comprises the callback functions that
	deliver filtered data to the demux client. Unlike the other DVB
	kABIs, these functions are provided by the client and called from
	the demux code.</para>
	<para>The function pointers of this abstract interface are not
	packed into a structure as in the other demux APIs, because the
	callback functions are registered and used independent of each
	other. As an example, it is possible for the API client to provide
	several callback functions for receiving TS packets and no
	callbacks for PES packets or sections.</para>
	<para>The functions that implement the callback API need not be
	re-entrant: when a demux driver calls one of these functions,
	the driver is not allowed to call the function again before
	the original call returns. If a callback is triggered by a
	hardware interrupt, it is recommended to use the Linux
	&#8220;bottom half&#8221; mechanism or start a tasklet instead of
	making the callback function call directly from a hardware
	interrupt.</para>
	<para>This mechanism is implemented by
	<link linkend='API-dmx-ts-cb'>dmx_ts_cb()</link> and
	<link linkend='API-dmx-section-cb'>dmx_section_cb()</link>.</para>
    </section>

<!-- drivers/media/dvb-core/demux.h -->
<refentry id="API-enum-ts-filter-type">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum ts_filter_type</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum ts_filter_type</refname>
 <refpurpose>
  filter type bitmap for dmx_ts_feed.<function>set</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum ts_filter_type {
  TS_PACKET,
  TS_PAYLOAD_ONLY,
  TS_DECODER,
  TS_DEMUX
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>TS_PACKET</term>
      <listitem><para>
Send TS packets (188 bytes) to callback (default).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>TS_PAYLOAD_ONLY</term>
      <listitem><para>
In case TS_PACKET is set, only send the TS payload
(&lt;=184 bytes per packet) to callback
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>TS_DECODER</term>
      <listitem><para>
Send stream to built-in decoder (if present).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>TS_DEMUX</term>
      <listitem><para>
In case TS_PACKET is set, send the TS to the demux
device, not to the dvr device
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-struct-dmx-ts-feed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dmx_ts_feed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dmx_ts_feed</refname>
 <refpurpose>
     Structure that contains a TS feed filter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dmx_ts_feed {
  int is_filtering;
  struct dmx_demux * parent;
  void * priv;
  int (* set) (struct dmx_ts_feed *feed,u16 pid,int type,enum dmx_ts_pes pes_type,size_t circular_buffer_size,struct timespec timeout);
  int (* start_filtering) (struct dmx_ts_feed *feed);
  int (* stop_filtering) (struct dmx_ts_feed *feed);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>is_filtering</term>
      <listitem><para>
   Set to non-zero when filtering in progress
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>parent</term>
      <listitem><para>
   pointer to struct dmx_demux
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>priv</term>
      <listitem><para>
   pointer to private data of the API client
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set</term>
      <listitem><para>
   sets the TS filter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start_filtering</term>
      <listitem><para>
   starts TS filtering
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>stop_filtering</term>
      <listitem><para>
   stops TS filtering
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   A TS feed is typically mapped to a hardware PID filter on the demux chip.
   Using this API, the client can set the filtering properties to start/stop
   filtering TS packets on a particular TS feed.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-dmx-section-filter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dmx_section_filter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dmx_section_filter</refname>
 <refpurpose>
     Structure that describes a section filter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dmx_section_filter {
  u8 filter_value[DMX_MAX_FILTER_SIZE];
  u8 filter_mask[DMX_MAX_FILTER_SIZE];
  u8 filter_mode[DMX_MAX_FILTER_SIZE];
  struct dmx_section_feed * parent;
  void * priv;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>filter_value[DMX_MAX_FILTER_SIZE]</term>
      <listitem><para>
   Contains up to 16 bytes (128 bits) of the TS section header
   that will be matched by the section filter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>filter_mask[DMX_MAX_FILTER_SIZE]</term>
      <listitem><para>
   Contains a 16 bytes (128 bits) filter mask with the bits
   specified by <parameter>filter_value</parameter> that will be used on the filter
   match logic.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>filter_mode[DMX_MAX_FILTER_SIZE]</term>
      <listitem><para>
   Contains a 16 bytes (128 bits) filter mode.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>parent</term>
      <listitem><para>
   Pointer to struct dmx_section_feed.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>priv</term>
      <listitem><para>
   Pointer to private data of the API client.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   The <parameter>filter_mask</parameter> controls which bits of <parameter>filter_value</parameter> are compared with
   the section headers/payload. On a binary value of 1 in filter_mask, the
   corresponding bits are compared. The filter only accepts sections that are
   equal to filter_value in all the tested bit positions.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-dmx-section-feed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dmx_section_feed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dmx_section_feed</refname>
 <refpurpose>
     Structure that contains a section feed filter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dmx_section_feed {
  int is_filtering;
  struct dmx_demux * parent;
  void * priv;
  int check_crc;
  int (* set) (struct dmx_section_feed *feed,u16 pid,size_t circular_buffer_size,int check_crc);
  int (* allocate_filter) (struct dmx_section_feed *feed,struct dmx_section_filter **filter);
  int (* release_filter) (struct dmx_section_feed *feed,struct dmx_section_filter *filter);
  int (* start_filtering) (struct dmx_section_feed *feed);
  int (* stop_filtering) (struct dmx_section_feed *feed);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>is_filtering</term>
      <listitem><para>
   Set to non-zero when filtering in progress
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>parent</term>
      <listitem><para>
   pointer to struct dmx_demux
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>priv</term>
      <listitem><para>
   pointer to private data of the API client
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>check_crc</term>
      <listitem><para>
   If non-zero, check the CRC values of filtered sections.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set</term>
      <listitem><para>
   sets the section filter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>allocate_filter</term>
      <listitem><para>
   This function is used to allocate a section filter on
   the demux. It should only be called when no filtering
   is in progress on this section feed. If a filter cannot
   be allocated, the function fails with -ENOSPC.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release_filter</term>
      <listitem><para>
   This function releases all the resources of a
   previously allocated section filter. The function
   should not be called while filtering is in progress
   on this section feed. After calling this function,
   the caller should not try to dereference the filter
   pointer.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start_filtering</term>
      <listitem><para>
   starts section filtering
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>stop_filtering</term>
      <listitem><para>
   stops section filtering
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   A TS feed is typically mapped to a hardware PID filter on the demux chip.
   Using this API, the client can set the filtering properties to start/stop
   filtering TS packets on a particular TS feed.
</para>
</refsect1>
</refentry>

<refentry id="API-dmx-ts-cb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmx_ts_cb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmx_ts_cb</refname>
 <refpurpose>
     DVB demux TS filter callback function prototype
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dmx_ts_cb </function></funcdef>
   <paramdef>const u8 * <parameter>buffer1</parameter></paramdef>
   <paramdef>size_t <parameter>buffer1_length</parameter></paramdef>
   <paramdef>const u8 * <parameter>buffer2</parameter></paramdef>
   <paramdef>size_t <parameter>buffer2_length</parameter></paramdef>
   <paramdef><link linkend="API-struct-dmx-ts-feed">struct dmx_ts_feed</link> * <parameter>source</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buffer1</parameter></term>
   <listitem>
    <para>
     Pointer to the start of the filtered TS packets.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer1_length</parameter></term>
   <listitem>
    <para>
     Length of the TS data in buffer1.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer2</parameter></term>
   <listitem>
    <para>
     Pointer to the tail of the filtered TS packets, or NULL.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer2_length</parameter></term>
   <listitem>
    <para>
     Length of the TS data in buffer2.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>source</parameter></term>
   <listitem>
    <para>
     Indicates which TS feed is the source of the callback.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function callback prototype, provided by the client of the demux API,
   is called from the demux code. The function is only called when filtering
   on ae TS feed has been enabled using the <function>start_filtering</function> function at
   the <structname><link linkend="API-struct-dmx-demux">dmx_demux</link></structname>.
   Any TS packets that match the filter settings are copied to a circular
   buffer. The filtered TS packets are delivered to the client using this
   callback function. The size of the circular buffer is controlled by the
   circular_buffer_size parameter of the <structname><link linkend="API-struct-dmx-ts-feed">dmx_ts_feed</link></structname>.<parameter>set</parameter> function.
   It is expected that the <parameter>buffer1</parameter> and <parameter>buffer2</parameter> callback parameters point to
   addresses within the circular buffer, but other implementations are also
   possible. Note that the called party should not try to free the memory
   the <parameter>buffer1</parameter> and <parameter>buffer2</parameter> parameters point to.
   </para><para>

   When this function is called, the <parameter>buffer1</parameter> parameter typically points to
   the start of the first undelivered TS packet within a circular buffer.
   The <parameter>buffer2</parameter> buffer parameter is normally NULL, except when the received
   TS packets have crossed the last address of the circular buffer and
   ”wrapped” to the beginning of the buffer. In the latter case the <parameter>buffer1</parameter>
   parameter would contain an address within the circular buffer, while the
   <parameter>buffer2</parameter> parameter would contain the first address of the circular buffer.
   The number of bytes delivered with this function (i.e. <parameter>buffer1_length</parameter> +
   <parameter>buffer2_length</parameter>) is usually equal to the value of callback_length parameter
   given in the <function>set</function> function, with one exception: if a timeout occurs before
   receiving callback_length bytes of TS data, any undelivered packets are
   immediately delivered to the client by calling this function. The timeout
   duration is controlled by the <function>set</function> function in the TS Feed API.
   </para><para>

   If a TS packet is received with errors that could not be fixed by the
   TS-level forward error correction (FEC), the Transport_error_indicator
   flag of the TS packet header should be set. The TS packet should not be
   discarded, as the error can possibly be corrected by a higher layer
   protocol. If the called party is slow in processing the callback, it
   is possible that the circular buffer eventually fills up. If this happens,
   the demux driver should discard any TS packets received while the buffer
   is full and return -EOVERFLOW.
   </para><para>

   The type of data returned to the callback can be selected by the
   <structname><link linkend="API-struct-dmx-ts-feed">dmx_ts_feed</link></structname>.<parameter>set</parameter> function. The type parameter decides if the raw
   TS packet (TS_PACKET) or just the payload (TS_PACKET|TS_PAYLOAD_ONLY)
   should be returned. If additionally the TS_DECODER bit is set the stream
   will also be sent to the hardware MPEG decoder.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0, on success;
   -EOVERFLOW, on buffer overflow.
</para>
</refsect1>
</refentry>

<refentry id="API-dmx-section-cb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmx_section_cb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmx_section_cb</refname>
 <refpurpose>
     DVB demux TS filter callback function prototype
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dmx_section_cb </function></funcdef>
   <paramdef>const u8 * <parameter>buffer1</parameter></paramdef>
   <paramdef>size_t <parameter>buffer1_len</parameter></paramdef>
   <paramdef>const u8 * <parameter>buffer2</parameter></paramdef>
   <paramdef>size_t <parameter>buffer2_len</parameter></paramdef>
   <paramdef><link linkend="API-struct-dmx-section-filter">struct dmx_section_filter</link> * <parameter>source</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buffer1</parameter></term>
   <listitem>
    <para>
     Pointer to the start of the filtered section, e.g.
     within the circular buffer of the demux driver.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer1_len</parameter></term>
   <listitem>
    <para>
     Length of the filtered section data in <parameter>buffer1</parameter>,
     including headers and CRC.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer2</parameter></term>
   <listitem>
    <para>
     Pointer to the tail of the filtered section data,
     or NULL. Useful to handle the wrapping of a
     circular buffer.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer2_len</parameter></term>
   <listitem>
    <para>
     Length of the filtered section data in <parameter>buffer2</parameter>,
     including headers and CRC.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>source</parameter></term>
   <listitem>
    <para>
     Indicates which section feed is the source of the
     callback.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function callback prototype, provided by the client of the demux API,
   is called from the demux code. The function is only called when
   filtering of sections has been enabled using the function
   <structname><link linkend="API-struct-dmx-ts-feed">dmx_ts_feed</link></structname>.<parameter>start_filtering</parameter>. When the demux driver has received a
   complete section that matches at least one section filter, the client
   is notified via this callback function. Normally this function is called
   for each received section; however, it is also possible to deliver
   multiple sections with one callback, for example when the system load
   is high. If an error occurs while receiving a section, this
   function should be called with the corresponding error type set in the
   success field, whether or not there is data to deliver. The Section Feed
   implementation should maintain a circular buffer for received sections.
   However, this is not necessary if the Section Feed API is implemented as
   a client of the TS Feed API, because the TS Feed implementation then
   buffers the received data. The size of the circular buffer can be
   configured using the <structname><link linkend="API-struct-dmx-ts-feed">dmx_ts_feed</link></structname>.<parameter>set</parameter> function in the Section Feed API.
   If there is no room in the circular buffer when a new section is received,
   the section must be discarded. If this happens, the value of the success
   parameter should be DMX_OVERRUN_ERROR on the next callback.
</para>
</refsect1>
</refentry>

<refentry id="API-enum-dmx-frontend-source">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum dmx_frontend_source</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum dmx_frontend_source</refname>
 <refpurpose>
     Used to identify the type of frontend
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum dmx_frontend_source {
  DMX_MEMORY_FE,
  DMX_FRONTEND_0
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>DMX_MEMORY_FE</term>
      <listitem><para>
   The source of the demux is memory. It means that
   the MPEG-TS to be filtered comes from userspace,
   via <function>write</function> syscall.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>DMX_FRONTEND_0</term>
      <listitem><para>
   The source of the demux is a frontend connected
   to the demux.
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-struct-dmx-frontend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dmx_frontend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dmx_frontend</refname>
 <refpurpose>
     Structure that lists the frontends associated with a demux
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dmx_frontend {
  struct list_head connectivity_list;
  enum dmx_frontend_source source;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>connectivity_list</term>
      <listitem><para>
   List of front-ends that can be connected to a
   particular demux;
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>source</term>
      <listitem><para>
   Type of the frontend.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>FIXME</title>
<para>
   this structure should likely be replaced soon by some
   media-controller based logic.
</para>
</refsect1>
</refentry>

<refentry id="API-enum-dmx-demux-caps">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum dmx_demux_caps</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum dmx_demux_caps</refname>
 <refpurpose>
     MPEG-2 TS Demux capabilities bitmap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum dmx_demux_caps {
  DMX_TS_FILTERING,
  DMX_SECTION_FILTERING,
  DMX_MEMORY_BASED_FILTERING
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>DMX_TS_FILTERING</term>
      <listitem><para>
   set if TS filtering is supported;
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>DMX_SECTION_FILTERING</term>
      <listitem><para>
   set if section filtering is supported;
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>DMX_MEMORY_BASED_FILTERING</term>
      <listitem><para>
   set if <function>write</function> available.
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Those flags are OR'ed in the <structname><link linkend="API-struct-dmx-demux">dmx_demux</link></structname>.<structname>capabilities</structname> field
</para>
</refsect1>
</refentry>

<refentry id="API-struct-dmx-demux">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct dmx_demux</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct dmx_demux</refname>
 <refpurpose>
     Structure that contains the demux capabilities and callbacks.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct dmx_demux {
  enum dmx_demux_caps capabilities;
  struct dmx_frontend * frontend;
  void * priv;
  int (* open) (struct dmx_demux *demux);
  int (* close) (struct dmx_demux *demux);
  int (* write) (struct dmx_demux *demux, const char __user *buf,size_t count);
  int (* allocate_ts_feed) (struct dmx_demux *demux,struct dmx_ts_feed **feed,dmx_ts_cb callback);
  int (* release_ts_feed) (struct dmx_demux *demux,struct dmx_ts_feed *feed);
  int (* allocate_section_feed) (struct dmx_demux *demux,struct dmx_section_feed **feed,dmx_section_cb callback);
  int (* release_section_feed) (struct dmx_demux *demux,struct dmx_section_feed *feed);
  int (* add_frontend) (struct dmx_demux *demux,struct dmx_frontend *frontend);
  int (* remove_frontend) (struct dmx_demux *demux,struct dmx_frontend *frontend);
  struct list_head *(* get_frontends) (struct dmx_demux *demux);
  int (* connect_frontend) (struct dmx_demux *demux,struct dmx_frontend *frontend);
  int (* disconnect_frontend) (struct dmx_demux *demux);
  int (* get_pes_pids) (struct dmx_demux *demux, u16 *pids);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>capabilities</term>
      <listitem><para>
   Bitfield of capability flags.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>frontend</term>
      <listitem><para>
   Front-end connected to the demux
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>priv</term>
      <listitem><para>
   Pointer to private data of the API client
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>open</term>
      <listitem><para>
   This function reserves the demux for use by the caller and, if
   necessary, initializes the demux. When the demux is no longer needed,
   the function <parameter>close</parameter> should be called. It should be possible for
   multiple clients to access the demux at the same time. Thus, the
   function implementation should increment the demux usage count when
   <parameter>open</parameter> is called and decrement it when <parameter>close</parameter> is called.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   It returns
   0 on success;
   -EUSERS, if maximum usage count was reached;
   -EINVAL, on bad parameter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>close</term>
      <listitem><para>
   This function reserves the demux for use by the caller and, if
   necessary, initializes the demux. When the demux is no longer needed,
   the function <parameter>close</parameter> should be called. It should be possible for
   multiple clients to access the demux at the same time. Thus, the
   function implementation should increment the demux usage count when
   <parameter>open</parameter> is called and decrement it when <parameter>close</parameter> is called.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   It returns
   0 on success;
   -ENODEV, if demux was not in use (e. g. no users);
   -EINVAL, on bad parameter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>write</term>
      <listitem><para>
   This function provides the demux driver with a memory buffer
   containing TS packets. Instead of receiving TS packets from the DVB
   front-end, the demux driver software will read packets from memory.
   Any clients of this demux with active TS, PES or Section filters will
   receive filtered data via the Demux callback API (see 0). The function
   returns when all the data in the buffer has been consumed by the demux.
   Demux hardware typically cannot read TS from memory. If this is the
   case, memory-based filtering has to be implemented entirely in software.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   The <parameter>buf</parameter> function parameter contains a pointer to the TS data in
   kernel-space memory.
   The <parameter>count</parameter> function parameter contains the length of the TS data.
   It returns
   0 on success;
   -ERESTARTSYS, if mutex lock was interrupted;
   -EINTR, if a signal handling is pending;
   -ENODEV, if demux was removed;
   -EINVAL, on bad parameter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>allocate_ts_feed</term>
      <listitem><para>
   Allocates a new TS feed, which is used to filter the TS
   packets carrying a certain PID. The TS feed normally corresponds to a
   hardware PID filter on the demux chip.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   The <parameter>feed</parameter> function parameter contains a pointer to the TS feed API and
   instance data.
   The <parameter>callback</parameter> function parameter contains a pointer to the callback
   function for passing received TS packet.
   It returns
   0 on success;
   -ERESTARTSYS, if mutex lock was interrupted;
   -EBUSY, if no more TS feeds is available;
   -EINVAL, on bad parameter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release_ts_feed</term>
      <listitem><para>
   Releases the resources allocated with <parameter>allocate_ts_feed</parameter>.
   Any filtering in progress on the TS feed should be stopped before
   calling this function.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   The <parameter>feed</parameter> function parameter contains a pointer to the TS feed API and
   instance data.
   It returns
   0 on success;
   -EINVAL on bad parameter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>allocate_section_feed</term>
      <listitem><para>
   Allocates a new section feed, i.e. a demux resource
   for filtering and receiving sections. On platforms with hardware
   support for section filtering, a section feed is directly mapped to
   the demux HW. On other platforms, TS packets are first PID filtered in
   hardware and a hardware section filter then emulated in software. The
   caller obtains an API pointer of type dmx_section_feed_t as an out
   parameter. Using this API the caller can set filtering parameters and
   start receiving sections.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   The <parameter>feed</parameter> function parameter contains a pointer to the TS feed API and
   instance data.
   The <parameter>callback</parameter> function parameter contains a pointer to the callback
   function for passing received TS packet.
   It returns
   0 on success;
   -EBUSY, if no more TS feeds is available;
   -EINVAL, on bad parameter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release_section_feed</term>
      <listitem><para>
   Releases the resources allocated with
   <parameter>allocate_section_feed</parameter>, including allocated filters. Any filtering in
   progress on the section feed should be stopped before calling this
   function.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   The <parameter>feed</parameter> function parameter contains a pointer to the TS feed API and
   instance data.
   It returns
   0 on success;
   -EINVAL, on bad parameter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>add_frontend</term>
      <listitem><para>
   Registers a connectivity between a demux and a front-end,
   i.e., indicates that the demux can be connected via a call to
   <parameter>connect_frontend</parameter> to use the given front-end as a TS source. The
   client of this function has to allocate dynamic or static memory for
   the frontend structure and initialize its fields before calling this
   function. This function is normally called during the driver
   initialization. The caller must not free the memory of the frontend
   struct before successfully calling <parameter>remove_frontend</parameter>.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   The <parameter>frontend</parameter> function parameter contains a pointer to the front-end
   instance data.
   It returns
   0 on success;
   -EINVAL, on bad parameter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>remove_frontend</term>
      <listitem><para>
   Indicates that the given front-end, registered by a call
   to <parameter>add_frontend</parameter>, can no longer be connected as a TS source by this
   demux. The function should be called when a front-end driver or a demux
   driver is removed from the system. If the front-end is in use, the
   function fails with the return value of -EBUSY. After successfully
   calling this function, the caller can free the memory of the frontend
   struct if it was dynamically allocated before the <parameter>add_frontend</parameter>
   operation.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   The <parameter>frontend</parameter> function parameter contains a pointer to the front-end
   instance data.
   It returns
   0 on success;
   -ENODEV, if the front-end was not found,
   -EINVAL, on bad parameter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_frontends</term>
      <listitem><para>
   Provides the APIs of the front-ends that have been
   registered for this demux. Any of the front-ends obtained with this
   call can be used as a parameter for <parameter>connect_frontend</parameter>. The include
   file demux.h contains the macro <function>DMX_FE_ENTRY</function> for converting an
   element of the generic type struct <structname>list_head</structname> * to the type
   struct <structname><link linkend="API-struct-dmx-frontend">dmx_frontend</link></structname> *. The caller must not free the memory of any of
   the elements obtained via this function call.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   It returns a struct list_head pointer to the list of front-end
   interfaces, or NULL in the case of an empty list.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connect_frontend</term>
      <listitem><para>
   Connects the TS output of the front-end to the input of
   the demux. A demux can only be connected to a front-end registered to
   the demux with the function <parameter>add_frontend</parameter>. It may or may not be
   possible to connect multiple demuxes to the same front-end, depending
   on the capabilities of the HW platform. When not used, the front-end
   should be released by calling <parameter>disconnect_frontend</parameter>.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   The <parameter>frontend</parameter> function parameter contains a pointer to the front-end
   instance data.
   It returns
   0 on success;
   -EINVAL, on bad parameter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>disconnect_frontend</term>
      <listitem><para>
   Disconnects the demux and a front-end previously
   connected by a <parameter>connect_frontend</parameter> call.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   It returns
   0 on success;
   -EINVAL on bad parameter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_pes_pids</term>
      <listitem><para>
   Get the PIDs for DMX_PES_AUDIO0, DMX_PES_VIDEO0,
   DMX_PES_TELETEXT0, DMX_PES_SUBTITLE0 and DMX_PES_PCR0.
   The <parameter>demux</parameter> function parameter contains a pointer to the demux API and
   instance data.
   The <parameter>pids</parameter> function parameter contains an array with five u16 elements
   where the PIDs will be stored.
   It returns
   0 on success;
   -EINVAL on bad parameter.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

    </sect1>
    <sect1><title>Remote Controller devices</title>
<!-- include/media/rc-core.h -->
<refentry id="API-struct-rc-scancode-filter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct rc_scancode_filter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct rc_scancode_filter</refname>
 <refpurpose>
  Filter scan codes.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct rc_scancode_filter {
  u32 data;
  u32 mask;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>data</term>
      <listitem><para>
Scancode data to match.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mask</term>
      <listitem><para>
Mask of bits of scancode to compare.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-enum-rc-filter-type">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum rc_filter_type</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum rc_filter_type</refname>
 <refpurpose>
     Filter type constants.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum rc_filter_type {
  RC_FILTER_NORMAL,
  RC_FILTER_WAKEUP,
  RC_FILTER_MAX
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>RC_FILTER_NORMAL</term>
      <listitem><para>
   Filter for normal operation.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>RC_FILTER_WAKEUP</term>
      <listitem><para>
   Filter for waking from suspend.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>RC_FILTER_MAX</term>
      <listitem><para>
   Number of filter types.
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-struct-rc-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct rc_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct rc_dev</refname>
 <refpurpose>
     represents a remote control device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct rc_dev {
  struct device dev;
  const struct attribute_group * sysfs_groups[5];
  const char * input_name;
  const char * input_phys;
  struct input_id input_id;
  char * driver_name;
  const char * map_name;
  struct rc_map rc_map;
  struct mutex lock;
  unsigned int minor;
  struct ir_raw_event_ctrl * raw;
  struct input_dev * input_dev;
  enum rc_driver_type driver_type;
  bool idle;
  u64 allowed_protocols;
  u64 enabled_protocols;
  u64 allowed_wakeup_protocols;
  u64 enabled_wakeup_protocols;
  struct rc_scancode_filter scancode_filter;
  struct rc_scancode_filter scancode_wakeup_filter;
  u32 scancode_mask;
  u32 users;
  void * priv;
  spinlock_t keylock;
  bool keypressed;
  unsigned long keyup_jiffies;
  struct timer_list timer_keyup;
  u32 last_keycode;
  enum rc_type last_protocol;
  u32 last_scancode;
  u8 last_toggle;
  u32 timeout;
  u32 min_timeout;
  u32 max_timeout;
  u32 rx_resolution;
  u32 tx_resolution;
  int (* change_protocol) (struct rc_dev *dev, u64 *rc_type);
  int (* change_wakeup_protocol) (struct rc_dev *dev, u64 *rc_type);
  int (* open) (struct rc_dev *dev);
  void (* close) (struct rc_dev *dev);
  int (* s_tx_mask) (struct rc_dev *dev, u32 mask);
  int (* s_tx_carrier) (struct rc_dev *dev, u32 carrier);
  int (* s_tx_duty_cycle) (struct rc_dev *dev, u32 duty_cycle);
  int (* s_rx_carrier_range) (struct rc_dev *dev, u32 min, u32 max);
  int (* tx_ir) (struct rc_dev *dev, unsigned *txbuf, unsigned n);
  void (* s_idle) (struct rc_dev *dev, bool enable);
  int (* s_learning_mode) (struct rc_dev *dev, int enable);
  int (* s_carrier_report) (struct rc_dev *dev, int enable);
  int (* s_filter) (struct rc_dev *dev,struct rc_scancode_filter *filter);
  int (* s_wakeup_filter) (struct rc_dev *dev,struct rc_scancode_filter *filter);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   driver model's view of this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sysfs_groups[5]</term>
      <listitem><para>
   sysfs attribute groups
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>input_name</term>
      <listitem><para>
   name of the input child device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>input_phys</term>
      <listitem><para>
   physical path to the input child device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>input_id</term>
      <listitem><para>
   id of the input child device (struct input_id)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver_name</term>
      <listitem><para>
   name of the hardware driver which registered this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>map_name</term>
      <listitem><para>
   name of the default keymap
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rc_map</term>
      <listitem><para>
   current scan/key table
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
   used to ensure we've filled in all protocol details before
   anyone can call show_protocols or store_protocols
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>minor</term>
      <listitem><para>
   unique minor remote control device number
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>raw</term>
      <listitem><para>
   additional data for raw pulse/space devices
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>input_dev</term>
      <listitem><para>
   the input child device used to communicate events to userspace
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver_type</term>
      <listitem><para>
   specifies if protocol decoding is done in hardware or software
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>idle</term>
      <listitem><para>
   used to keep track of RX state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>allowed_protocols</term>
      <listitem><para>
   bitmask with the supported RC_BIT_* protocols
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enabled_protocols</term>
      <listitem><para>
   bitmask with the enabled RC_BIT_* protocols
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>allowed_wakeup_protocols</term>
      <listitem><para>
   bitmask with the supported RC_BIT_* wakeup protocols
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enabled_wakeup_protocols</term>
      <listitem><para>
   bitmask with the enabled RC_BIT_* wakeup protocols
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>scancode_filter</term>
      <listitem><para>
   scancode filter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>scancode_wakeup_filter</term>
      <listitem><para>
   scancode wakeup filters
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>scancode_mask</term>
      <listitem><para>
   some hardware decoders are not capable of providing the full
   scancode to the application. As this is a hardware limit, we can't do
   anything with it. Yet, as the same keycode table can be used with other
   devices, a mask is provided to allow its usage. Drivers should generally
   leave this field in blank
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>users</term>
      <listitem><para>
   number of current users of the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>priv</term>
      <listitem><para>
   driver-specific data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>keylock</term>
      <listitem><para>
   protects the remaining members of the struct
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>keypressed</term>
      <listitem><para>
   whether a key is currently pressed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>keyup_jiffies</term>
      <listitem><para>
   time (in jiffies) when the current keypress should be released
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>timer_keyup</term>
      <listitem><para>
   timer for releasing a keypress
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>last_keycode</term>
      <listitem><para>
   keycode of last keypress
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>last_protocol</term>
      <listitem><para>
   protocol of last keypress
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>last_scancode</term>
      <listitem><para>
   scancode of last keypress
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>last_toggle</term>
      <listitem><para>
   toggle value of last command
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>timeout</term>
      <listitem><para>
   optional time after which device stops sending data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>min_timeout</term>
      <listitem><para>
   minimum timeout supported by device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_timeout</term>
      <listitem><para>
   maximum timeout supported by device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_resolution</term>
      <listitem><para>
   resolution (in ns) of input sampler
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_resolution</term>
      <listitem><para>
   resolution (in ns) of output sampler
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>change_protocol</term>
      <listitem><para>
   allow changing the protocol used on hardware decoders
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>change_wakeup_protocol</term>
      <listitem><para>
   allow changing the protocol used for wakeup
   filtering
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>open</term>
      <listitem><para>
   callback to allow drivers to enable polling/irq when IR input device
   is opened.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>close</term>
      <listitem><para>
   callback to allow drivers to disable polling/irq when IR input device
   is opened.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_tx_mask</term>
      <listitem><para>
   set transmitter mask (for devices with multiple tx outputs)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_tx_carrier</term>
      <listitem><para>
   set transmit carrier frequency
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_tx_duty_cycle</term>
      <listitem><para>
   set transmit duty cycle (0% - 100%)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_rx_carrier_range</term>
      <listitem><para>
   inform driver about carrier it is expected to handle
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_ir</term>
      <listitem><para>
   transmit IR
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_idle</term>
      <listitem><para>
   enable/disable hardware idle mode, upon which,
   device doesn't interrupt host until it sees IR pulses
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_learning_mode</term>
      <listitem><para>
   enable wide band receiver used for learning
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_carrier_report</term>
      <listitem><para>
   enable carrier reports
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_filter</term>
      <listitem><para>
   set the scancode filter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>s_wakeup_filter</term>
      <listitem><para>
   set the wakeup scancode filter
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- include/media/lirc_dev.h -->
<refentry id="API-struct-lirc-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct lirc_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct lirc_driver</refname>
 <refpurpose>
  Defines the parameters on a LIRC driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct lirc_driver {
  char name[40];
  int minor;
  __u32 code_length;
  unsigned int buffer_size;
  int sample_rate;
  __u32 features;
  unsigned int chunk_size;
  void * data;
  int min_timeout;
  int max_timeout;
  int (* add_to_buf) (void *data, struct lirc_buffer *buf);
  struct lirc_buffer * rbuf;
  int (* set_use_inc) (void *data);
  void (* set_use_dec) (void *data);
  struct rc_dev * rdev;
  const struct file_operations * fops;
  struct device * dev;
  struct module * owner;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name[40]</term>
      <listitem><para>
this string will be used for logs
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>minor</term>
      <listitem><para>
indicates minor device (/dev/lirc) number for
registered driver if caller fills it with negative
value, then the first free minor number will be used
(if available).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>code_length</term>
      <listitem><para>
length of the remote control key code expressed in bits.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>buffer_size</term>
      <listitem><para>
Number of FIFO buffers with <parameter>chunk_size</parameter> size. If zero,
creates a buffer with BUFLEN size (16 bytes).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sample_rate</term>
      <listitem><para>
if zero, the device will wait for an event with a new
code to be parsed. Otherwise, specifies the sample
rate for polling. Value should be between 0
and HZ. If equal to HZ, it would mean one polling per
second.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>features</term>
      <listitem><para>
lirc compatible hardware features, like LIRC_MODE_RAW,
LIRC_CAN_*, as defined at include/media/lirc.h.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>chunk_size</term>
      <listitem><para>
Size of each FIFO buffer.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>data</term>
      <listitem><para>
it may point to any driver data and this pointer will
be passed to all callback functions.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>min_timeout</term>
      <listitem><para>
Minimum timeout for record. Valid only if
LIRC_CAN_SET_REC_TIMEOUT is defined.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_timeout</term>
      <listitem><para>
Maximum timeout for record. Valid only if
LIRC_CAN_SET_REC_TIMEOUT is defined.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>add_to_buf</term>
      <listitem><para>
add_to_buf will be called after specified period of the
time or triggered by the external event, this behavior
depends on value of the sample_rate this function will
be called in user context. This routine should return
0 if data was added to the buffer and -ENODATA if none
was available. This should add some number of bits
evenly divisible by code_length to the buffer.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rbuf</term>
      <listitem><para>
if not NULL, it will be used as a read buffer, you will
have to write to the buffer by other means, like irq's
(see also lirc_serial.c).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_use_inc</term>
      <listitem><para>
set_use_inc will be called after device is opened
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_use_dec</term>
      <listitem><para>
set_use_dec will be called after device is closed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rdev</term>
      <listitem><para>
Pointed to struct rc_dev associated with the LIRC
device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fops</term>
      <listitem><para>
file_operations for drivers which don't fit the current
driver model.
Some ioctl's can be directly handled by lirc_dev if the
driver's ioctl function is NULL or if it returns
-ENOIOCTLCMD (see also lirc_serial.c).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev</term>
      <listitem><para>
pointer to the struct device associated with the LIRC
device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>owner</term>
      <listitem><para>
the module owning this struct
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

    </sect1>
    <sect1><title>Media Controller devices</title>
<!-- include/media/media-device.h -->
<refentry id="API-struct-media-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct media_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct media_device</refname>
 <refpurpose>
  Media device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct media_device {
  struct device * dev;
  struct media_devnode devnode;
  char model[32];
  char serial[40];
  char bus_info[32];
  u32 hw_revision;
  u32 driver_version;
  u32 entity_id;
  struct list_head entities;
  spinlock_t lock;
  struct mutex graph_mutex;
  int (* link_notify) (struct media_link *link, u32 flags,unsigned int notification);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
Parent device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>devnode</term>
      <listitem><para>
Media device node
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>model[32]</term>
      <listitem><para>
Device model name
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>serial[40]</term>
      <listitem><para>
Device serial number (optional)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus_info[32]</term>
      <listitem><para>
Unique and stable device location identifier
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>hw_revision</term>
      <listitem><para>
Hardware device revision
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver_version</term>
      <listitem><para>
Device driver version
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>entity_id</term>
      <listitem><para>
ID of the next entity to be registered
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>entities</term>
      <listitem><para>
List of registered entities
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
Entities list lock
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>graph_mutex</term>
      <listitem><para>
Entities graph operation lock
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>link_notify</term>
      <listitem><para>
Link state change notification callback
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This structure represents an abstract high-level media device. It allows easy
   access to entities and provides basic media device-level support. The
   structure can be allocated directly or embedded in a larger structure.
   </para><para>

   The parent <parameter>dev</parameter> is a physical device. It must be set before registering the
   media device.
   </para><para>

   <parameter>model</parameter> is a descriptive model name exported through sysfs. It doesn't have to
   be unique.
</para>
</refsect1>
</refentry>

<!-- include/media/media-devnode.h -->
<refentry id="API-struct-media-devnode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct media_devnode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct media_devnode</refname>
 <refpurpose>
  Media device node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct media_devnode {
  const struct media_file_operations * fops;
  struct device dev;
  struct cdev cdev;
  struct device * parent;
  int minor;
  unsigned long flags;
  void (* release) (struct media_devnode *mdev);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>fops</term>
      <listitem><para>
pointer to struct media_file_operations with media device ops
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev</term>
      <listitem><para>
struct device pointer for the media controller device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cdev</term>
      <listitem><para>
struct cdev pointer character device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>parent</term>
      <listitem><para>
parent device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>minor</term>
      <listitem><para>
device node minor number
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
flags, combination of the MEDIA_FLAG_* constants
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release</term>
      <listitem><para>
release callback called at the end of <function>media_devnode_release</function>
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This structure represents a media-related device node.
   </para><para>

   The <parameter>parent</parameter> is a physical device. It must be set by core or device drivers
   before registering the node.
</para>
</refsect1>
</refentry>

<!-- include/media/media-entity.h -->
<refentry id="API-struct-media-entity-operations">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct media_entity_operations</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct media_entity_operations</refname>
 <refpurpose>
  Media entity operations
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct media_entity_operations {
  int (* link_setup) (struct media_entity *entity,const struct media_pad *local,const struct media_pad *remote, u32 flags);
  int (* link_validate) (struct media_link *link);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>link_setup</term>
      <listitem><para>
Notify the entity of link changes. The operation can
return an error, in which case link setup will be
cancelled. Optional.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>link_validate</term>
      <listitem><para>
Return whether a link is valid from the entity point of
view. The <function>media_entity_pipeline_start</function> function
validates all links by calling this operation. Optional.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

    </sect1>

  </chapter>

  <chapter id="uart16x50">
     <title>16x50 UART Driver</title>
<!-- drivers/tty/serial/serial_core.c -->
<refentry id="API-uart-update-timeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_update_timeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_update_timeout</refname>
 <refpurpose>
  update per-port FIFO timeout.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uart_update_timeout </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
   <paramdef>unsigned int <parameter>cflag</parameter></paramdef>
   <paramdef>unsigned int <parameter>baud</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     uart_port structure describing the port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cflag</parameter></term>
   <listitem>
    <para>
     termios cflag value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>baud</parameter></term>
   <listitem>
    <para>
     speed of the port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set the port FIFO timeout value.  The <parameter>cflag</parameter> value should
   reflect the actual hardware settings.
</para>
</refsect1>
</refentry>

<refentry id="API-uart-get-baud-rate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_get_baud_rate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_get_baud_rate</refname>
 <refpurpose>
     return baud rate for a particular port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>uart_get_baud_rate </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
   <paramdef>struct ktermios * <parameter>termios</parameter></paramdef>
   <paramdef>struct ktermios * <parameter>old</parameter></paramdef>
   <paramdef>unsigned int <parameter>min</parameter></paramdef>
   <paramdef>unsigned int <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     uart_port structure describing the port in question.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>termios</parameter></term>
   <listitem>
    <para>
     desired termios settings.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     old termios (or NULL)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     minimum acceptable baud rate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     maximum acceptable baud rate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Decode the termios structure into a numeric baud rate,
   taking account of the magic 38400 baud rate (with spd_*
   flags), and mapping the <constant>B0</constant> rate to 9600 baud.
   </para><para>

   If the new baud rate is invalid, try the old termios setting.
   If it's still invalid, we try 9600 baud.
   </para><para>

   Update the <parameter>termios</parameter> structure to reflect the baud rate
   we're actually going to be using. Don't do this for the case
   where B0 is requested (<quote>hang up</quote>).
</para>
</refsect1>
</refentry>

<refentry id="API-uart-get-divisor">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_get_divisor</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_get_divisor</refname>
 <refpurpose>
     return uart clock divisor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>uart_get_divisor </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
   <paramdef>unsigned int <parameter>baud</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     uart_port structure describing the port.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>baud</parameter></term>
   <listitem>
    <para>
     desired baud rate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calculate the uart clock divisor for the port.
</para>
</refsect1>
</refentry>

<refentry id="API-uart-console-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_console_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_console_write</refname>
 <refpurpose>
     write a console message to a serial port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uart_console_write </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
   <paramdef>void (*<parameter>putchar</parameter>)
     <funcparams>struct uart_port *, int</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     the port to write the message
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     array of characters
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of characters in string to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>putchar</parameter></term>
   <listitem>
    <para>
     function to write character to port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-uart-parse-earlycon">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_parse_earlycon</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_parse_earlycon</refname>
 <refpurpose>
     Parse earlycon options
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>uart_parse_earlycon </function></funcdef>
   <paramdef>char * <parameter>p</parameter></paramdef>
   <paramdef>unsigned char * <parameter>iotype</parameter></paramdef>
   <paramdef>unsigned long * <parameter>addr</parameter></paramdef>
   <paramdef>char ** <parameter>options</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     ptr to 2nd field (ie., just beyond '&lt;name&gt;,')
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>iotype</parameter></term>
   <listitem>
    <para>
     ptr for decoded iotype (out)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     ptr for decoded mapbase/iobase (out)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>options</parameter></term>
   <listitem>
    <para>
     ptr for &lt;options&gt; field; NULL if not present (out)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Decodes earlycon kernel command line parameters of the form
   earlycon=&lt;name&gt;,io|mmio|mmio32|mmio32be|mmio32native,&lt;addr&gt;,&lt;options&gt;
   console=&lt;name&gt;,io|mmio|mmio32|mmio32be|mmio32native,&lt;addr&gt;,&lt;options&gt;
   </para><para>

   The optional form
   earlycon=&lt;name&gt;,0x&lt;addr&gt;,&lt;options&gt;
   console=&lt;name&gt;,0x&lt;addr&gt;,&lt;options&gt;
   is also accepted; the returned <parameter>iotype</parameter> will be UPIO_MEM.
   </para><para>

   Returns 0 on success or -EINVAL on failure
</para>
</refsect1>
</refentry>

<refentry id="API-uart-parse-options">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_parse_options</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_parse_options</refname>
 <refpurpose>
     Parse serial port baud/parity/bits/flow control.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uart_parse_options </function></funcdef>
   <paramdef>char * <parameter>options</parameter></paramdef>
   <paramdef>int * <parameter>baud</parameter></paramdef>
   <paramdef>int * <parameter>parity</parameter></paramdef>
   <paramdef>int * <parameter>bits</parameter></paramdef>
   <paramdef>int * <parameter>flow</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>options</parameter></term>
   <listitem>
    <para>
     pointer to option string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>baud</parameter></term>
   <listitem>
    <para>
     pointer to an 'int' variable for the baud rate.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parity</parameter></term>
   <listitem>
    <para>
     pointer to an 'int' variable for the parity.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bits</parameter></term>
   <listitem>
    <para>
     pointer to an 'int' variable for the number of data bits.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flow</parameter></term>
   <listitem>
    <para>
     pointer to an 'int' variable for the flow control character.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   uart_parse_options decodes a string containing the serial console
   options.  The format of the string is &lt;baud&gt;&lt;parity&gt;&lt;bits&gt;&lt;flow&gt;,
</para>
</refsect1>
<refsect1>
<title>eg</title>
<para>
   115200n8r
</para>
</refsect1>
</refentry>

<refentry id="API-uart-set-options">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_set_options</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_set_options</refname>
 <refpurpose>
     setup the serial console parameters
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>uart_set_options </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
   <paramdef>struct console * <parameter>co</parameter></paramdef>
   <paramdef>int <parameter>baud</parameter></paramdef>
   <paramdef>int <parameter>parity</parameter></paramdef>
   <paramdef>int <parameter>bits</parameter></paramdef>
   <paramdef>int <parameter>flow</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     pointer to the serial ports uart_port structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>co</parameter></term>
   <listitem>
    <para>
     console pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>baud</parameter></term>
   <listitem>
    <para>
     baud rate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parity</parameter></term>
   <listitem>
    <para>
     parity character - 'n' (none), 'o' (odd), 'e' (even)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bits</parameter></term>
   <listitem>
    <para>
     number of data bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flow</parameter></term>
   <listitem>
    <para>
     flow control character - 'r' (rts)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-uart-register-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_register_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_register_driver</refname>
 <refpurpose>
     register a driver with the uart core layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>uart_register_driver </function></funcdef>
   <paramdef>struct uart_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     low level driver structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register a uart driver with the core driver.  We in turn register
   with the tty layer, and initialise the core driver per-port state.
   </para><para>

   We have a proc file in /proc/tty/driver which is named after the
   normal driver.
   </para><para>

   drv-&gt;port should be NULL, and the per-port structures should be
   registered using uart_add_one_port after this call has succeeded.
</para>
</refsect1>
</refentry>

<refentry id="API-uart-unregister-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_unregister_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_unregister_driver</refname>
 <refpurpose>
     remove a driver from the uart core layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uart_unregister_driver </function></funcdef>
   <paramdef>struct uart_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     low level driver structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove all references to a driver from the core driver.  The low
   level driver must have removed all its ports via the
   <function><link linkend="API-uart-remove-one-port">uart_remove_one_port</link></function> if it registered them with <function><link linkend="API-uart-add-one-port">uart_add_one_port</link></function>.
   (ie, drv-&gt;port == NULL)
</para>
</refsect1>
</refentry>

<refentry id="API-uart-add-one-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_add_one_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_add_one_port</refname>
 <refpurpose>
     attach a driver-defined port structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>uart_add_one_port </function></funcdef>
   <paramdef>struct uart_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct uart_port * <parameter>uport</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     pointer to the uart low level driver structure for this port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uport</parameter></term>
   <listitem>
    <para>
     uart port structure to use for this port.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This allows the driver to register its own uart_port structure
   with the core driver.  The main purpose is to allow the low
   level uart drivers to expand uart_port, rather than having yet
   more levels of structures.
</para>
</refsect1>
</refentry>

<refentry id="API-uart-remove-one-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_remove_one_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_remove_one_port</refname>
 <refpurpose>
     detach a driver defined port structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>uart_remove_one_port </function></funcdef>
   <paramdef>struct uart_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct uart_port * <parameter>uport</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     pointer to the uart low level driver structure for this port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uport</parameter></term>
   <listitem>
    <para>
     uart port structure for this port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This unhooks (and hangs up) the specified port structure from the
   core driver.  No further calls will be made to the low-level code
   for this port.
</para>
</refsect1>
</refentry>

<refentry id="API-uart-handle-dcd-change">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_handle_dcd_change</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_handle_dcd_change</refname>
 <refpurpose>
     handle a change of carrier detect state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uart_handle_dcd_change </function></funcdef>
   <paramdef>struct uart_port * <parameter>uport</parameter></paramdef>
   <paramdef>unsigned int <parameter>status</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>uport</parameter></term>
   <listitem>
    <para>
     uart_port structure for the open port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>status</parameter></term>
   <listitem>
    <para>
     new carrier detect status, nonzero if active
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Caller must hold uport-&gt;lock
</para>
</refsect1>
</refentry>

<refentry id="API-uart-handle-cts-change">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_handle_cts_change</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_handle_cts_change</refname>
 <refpurpose>
     handle a change of clear-to-send state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uart_handle_cts_change </function></funcdef>
   <paramdef>struct uart_port * <parameter>uport</parameter></paramdef>
   <paramdef>unsigned int <parameter>status</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>uport</parameter></term>
   <listitem>
    <para>
     uart_port structure for the open port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>status</parameter></term>
   <listitem>
    <para>
     new clear to send status, nonzero if active
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Caller must hold uport-&gt;lock
</para>
</refsect1>
</refentry>

<refentry id="API-uart-insert-char">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_insert_char</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_insert_char</refname>
 <refpurpose>
     push a char to the uart layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uart_insert_char </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
   <paramdef>unsigned int <parameter>status</parameter></paramdef>
   <paramdef>unsigned int <parameter>overrun</parameter></paramdef>
   <paramdef>unsigned int <parameter>ch</parameter></paramdef>
   <paramdef>unsigned int <parameter>flag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     corresponding port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>status</parameter></term>
   <listitem>
    <para>
     state of the serial port RX buffer (LSR for 8250)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>overrun</parameter></term>
   <listitem>
    <para>
     mask of overrun bits in <parameter>status</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ch</parameter></term>
   <listitem>
    <para>
     character to push
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flag</parameter></term>
   <listitem>
    <para>
     flag for the character (see TTY_NORMAL and friends)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   User is responsible to call tty_flip_buffer_push when they are done with
   insertion.
</para>
</refsect1>
</refentry>

<!-- drivers/tty/serial/8250/8250_core.c -->
<refentry id="API-serial8250-get-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>serial8250_get_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>serial8250_get_port</refname>
 <refpurpose>
  retrieve struct uart_8250_port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct uart_8250_port * <function>serial8250_get_port </function></funcdef>
   <paramdef>int <parameter>line</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>line</parameter></term>
   <listitem>
    <para>
     serial line number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function retrieves struct uart_8250_port for the specific line.
   This struct *must* *not* be used to perform a 8250 or serial core operation
   which is not accessible otherwise. Its only purpose is to make the struct
   accessible to the runtime-pm callbacks for context suspend/restore.
   The lock assumption made here is none because runtime-pm suspend/resume
   callbacks should not be invoked if there is any operation performed on the
   port.
</para>
</refsect1>
</refentry>

<refentry id="API-serial8250-suspend-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>serial8250_suspend_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>serial8250_suspend_port</refname>
 <refpurpose>
     suspend one serial port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>serial8250_suspend_port </function></funcdef>
   <paramdef>int <parameter>line</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>line</parameter></term>
   <listitem>
    <para>
     serial line number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Suspend one serial port.
</para>
</refsect1>
</refentry>

<refentry id="API-serial8250-resume-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>serial8250_resume_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>serial8250_resume_port</refname>
 <refpurpose>
     resume one serial port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>serial8250_resume_port </function></funcdef>
   <paramdef>int <parameter>line</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>line</parameter></term>
   <listitem>
    <para>
     serial line number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Resume one serial port.
</para>
</refsect1>
</refentry>

<refentry id="API-serial8250-register-8250-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>serial8250_register_8250_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>serial8250_register_8250_port</refname>
 <refpurpose>
     register a serial port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>serial8250_register_8250_port </function></funcdef>
   <paramdef>struct uart_8250_port * <parameter>up</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>up</parameter></term>
   <listitem>
    <para>
     serial port template
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Configure the serial port specified by the request. If the
   port exists and is in use, it is hung up and unregistered
   first.
   </para><para>

   The port is then probed and if necessary the IRQ is autodetected
   If this fails an error is returned.
   </para><para>

   On success the port is ready to use and the line number is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-serial8250-unregister-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>serial8250_unregister_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>serial8250_unregister_port</refname>
 <refpurpose>
     remove a 16x50 serial port at runtime
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>serial8250_unregister_port </function></funcdef>
   <paramdef>int <parameter>line</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>line</parameter></term>
   <listitem>
    <para>
     serial line number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove one serial port.  This may not be called from interrupt
   context.  We hand the port back to the our control.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="fbdev">
     <title>Frame Buffer Library</title>

     <para>
       The frame buffer drivers depend heavily on four data structures.
       These structures are declared in include/linux/fb.h.  They are
       fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs.
       The last three can be made available to and from userland.
     </para>

     <para>
       fb_info defines the current state of a particular video card.
       Inside fb_info, there exists a fb_ops structure which is a
       collection of needed functions to make fbdev and fbcon work.
       fb_info is only visible to the kernel.
     </para>

     <para>
       fb_var_screeninfo is used to describe the features of a video card
       that are user defined.  With fb_var_screeninfo, things such as
       depth and the resolution may be defined.
     </para>

     <para>
       The next structure is fb_fix_screeninfo. This defines the
       properties of a card that are created when a mode is set and can't
       be changed otherwise.  A good example of this is the start of the
       frame buffer memory.  This "locks" the address of the frame buffer
       memory, so that it cannot be changed or moved.
     </para>

     <para>
       The last structure is fb_monospecs. In the old API, there was
       little importance for fb_monospecs. This allowed for forbidden things
       such as setting a mode of 800x600 on a fix frequency monitor. With
       the new API, fb_monospecs prevents such things, and if used
       correctly, can prevent a monitor from being cooked.  fb_monospecs
       will not be useful until kernels 2.5.x.
     </para>

     <sect1><title>Frame Buffer Memory</title>
<!-- drivers/video/fbdev/core/fbmem.c -->
<refentry id="API-register-framebuffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_framebuffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_framebuffer</refname>
 <refpurpose>
  registers a frame buffer device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_framebuffer </function></funcdef>
   <paramdef>struct fb_info * <parameter>fb_info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers a frame buffer device <parameter>fb_info</parameter>.
   </para><para>

   Returns negative errno on error, or zero for success.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-framebuffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_framebuffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_framebuffer</refname>
 <refpurpose>
     releases a frame buffer device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>unregister_framebuffer </function></funcdef>
   <paramdef>struct fb_info * <parameter>fb_info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregisters a frame buffer device <parameter>fb_info</parameter>.
   </para><para>

   Returns negative errno on error, or zero for success.
   </para><para>

   This function will also notify the framebuffer console
   to release the driver.
   </para><para>

   This is meant to be called within a driver's <function>module_exit</function>
   function. If this is called outside <function>module_exit</function>, ensure
   that the driver implements <function>fb_open</function> and <function>fb_release</function> to
   check that no processes are using the device.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-set-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_set_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_set_suspend</refname>
 <refpurpose>
     low level driver signals suspend
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_set_suspend </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>int <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     framebuffer affected
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     0 = resuming, !=0 = suspending
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is meant to be used by low level drivers to
   signal suspend/resume to the core &amp; clients.
   It must be called with the console semaphore held
</para>
</refsect1>
</refentry>

     </sect1>
<!--
     <sect1><title>Frame Buffer Console</title>
X!Edrivers/video/console/fbcon.c
     </sect1>
-->
     <sect1><title>Frame Buffer Colormap</title>
<!-- drivers/video/fbdev/core/fbcmap.c -->
<refentry id="API-fb-dealloc-cmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_dealloc_cmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_dealloc_cmap</refname>
 <refpurpose>
  deallocate a colormap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_dealloc_cmap </function></funcdef>
   <paramdef>struct fb_cmap * <parameter>cmap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmap</parameter></term>
   <listitem>
    <para>
     frame buffer colormap structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Deallocates a colormap that was previously allocated with
   <function>fb_alloc_cmap</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-copy-cmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_copy_cmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_copy_cmap</refname>
 <refpurpose>
     copy a colormap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_copy_cmap </function></funcdef>
   <paramdef>const struct fb_cmap * <parameter>from</parameter></paramdef>
   <paramdef>struct fb_cmap * <parameter>to</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     frame buffer colormap structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     frame buffer colormap structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copy contents of colormap from <parameter>from</parameter> to <parameter>to</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-set-cmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_set_cmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_set_cmap</refname>
 <refpurpose>
     set the colormap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_set_cmap </function></funcdef>
   <paramdef>struct fb_cmap * <parameter>cmap</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmap</parameter></term>
   <listitem>
    <para>
     frame buffer colormap structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets the colormap <parameter>cmap</parameter> for a screen of device <parameter>info</parameter>.
   </para><para>

   Returns negative errno on error, or zero on success.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-default-cmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_default_cmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_default_cmap</refname>
 <refpurpose>
     get default colormap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct fb_cmap * <function>fb_default_cmap </function></funcdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     size of palette for a depth
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Gets the default colormap for a specific screen depth.  <parameter>len</parameter>
   is the size of the palette for a particular screen depth.
   </para><para>

   Returns pointer to a frame buffer colormap structure.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-invert-cmaps">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_invert_cmaps</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_invert_cmaps</refname>
 <refpurpose>
     invert all defaults colormaps
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_invert_cmaps </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Invert all default colormaps.
</para>
</refsect1>
</refentry>

     </sect1>
<!-- FIXME:
  drivers/video/fbgen.c has no docs, which stuffs up the sgml.  Comment
  out until somebody adds docs.  KAO
     <sect1><title>Frame Buffer Generic Functions</title>
X!Idrivers/video/fbgen.c
     </sect1>
KAO -->
     <sect1><title>Frame Buffer Video Mode Database</title>
<!-- drivers/video/fbdev/core/modedb.c -->
<refentry id="API-fb-try-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_try_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_try_mode</refname>
 <refpurpose>
  test a video mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_try_mode </function></funcdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const struct fb_videomode * <parameter>mode</parameter></paramdef>
   <paramdef>unsigned int <parameter>bpp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     frame buffer user defined part of display
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     frame buffer video mode structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bpp</parameter></term>
   <listitem>
    <para>
     color depth in bits per pixel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Tries a video mode to test it's validity for device <parameter>info</parameter>.
   </para><para>

   Returns 1 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-delete-videomode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_delete_videomode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_delete_videomode</refname>
 <refpurpose>
     removed videomode entry from modelist
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_delete_videomode </function></funcdef>
   <paramdef>const struct fb_videomode * <parameter>mode</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     videomode to remove
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   Will remove all matching mode entries
</para>
</refsect1>
</refentry>

<!-- drivers/video/fbdev/core/modedb.c -->
<refentry id="API-fb-find-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_find_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_find_mode</refname>
 <refpurpose>
  finds a valid video mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_find_mode </function></funcdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const char * <parameter>mode_option</parameter></paramdef>
   <paramdef>const struct fb_videomode * <parameter>db</parameter></paramdef>
   <paramdef>unsigned int <parameter>dbsize</parameter></paramdef>
   <paramdef>const struct fb_videomode * <parameter>default_mode</parameter></paramdef>
   <paramdef>unsigned int <parameter>default_bpp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     frame buffer user defined part of display
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode_option</parameter></term>
   <listitem>
    <para>
     string video mode to find
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>db</parameter></term>
   <listitem>
    <para>
     video mode database
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dbsize</parameter></term>
   <listitem>
    <para>
     size of <parameter>db</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>default_mode</parameter></term>
   <listitem>
    <para>
     default video mode to fall back to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>default_bpp</parameter></term>
   <listitem>
    <para>
     default color depth in bits per pixel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds a suitable video mode, starting with the specified mode
   in <parameter>mode_option</parameter> with fallback to <parameter>default_mode</parameter>.  If
   <parameter>default_mode</parameter> fails, all modes in the video mode database will
   be tried.
   </para><para>

   Valid mode specifiers for <parameter>mode_option</parameter>:
   </para><para>

   &lt;xres&gt;x&lt;yres&gt;[M][R][-&lt;bpp&gt;][@&lt;refresh&gt;][i][m] or
   &lt;name&gt;[-&lt;bpp&gt;][@&lt;refresh&gt;]
   </para><para>

   with &lt;xres&gt;, &lt;yres&gt;, &lt;bpp&gt; and &lt;refresh&gt; decimal numbers and
   &lt;name&gt; a string.
   </para><para>

   If 'M' is present after yres (and before refresh/bpp if present),
   the function will compute the timings using VESA(tm) Coordinated
   Video Timings (CVT).  If 'R' is present after 'M', will compute with
   reduced blanking (for flatpanels).  If 'i' is present, compute
   interlaced mode.  If 'm' is present, add margins equal to 1.8%
   of xres rounded down to 8 pixels, and 1.8% of yres. The char
   'i' and 'm' must be after 'M' and 'R'. Example:
   </para><para>

   1024x768MR-8<parameter>60m</parameter> - Reduced blank with margins at 60Hz.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   The passed struct <parameter>var</parameter> is _not_ cleared!  This allows you
   to supply values for e.g. the grayscale and accel_flags fields.
   </para><para>

   Returns zero for failure, 1 if using specified <parameter>mode_option</parameter>,
   2 if using specified <parameter>mode_option</parameter> with an ignored refresh rate,
   3 if default mode is used, 4 if fall back to any valid mode.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-var-to-videomode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_var_to_videomode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_var_to_videomode</refname>
 <refpurpose>
     convert fb_var_screeninfo to fb_videomode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_var_to_videomode </function></funcdef>
   <paramdef>struct fb_videomode * <parameter>mode</parameter></paramdef>
   <paramdef>const struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_videomode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_var_screeninfo
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-fb-videomode-to-var">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_videomode_to_var</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_videomode_to_var</refname>
 <refpurpose>
     convert fb_videomode to fb_var_screeninfo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_videomode_to_var </function></funcdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>const struct fb_videomode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_var_screeninfo
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_videomode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-fb-mode-is-equal">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_mode_is_equal</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_mode_is_equal</refname>
 <refpurpose>
     compare 2 videomodes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_mode_is_equal </function></funcdef>
   <paramdef>const struct fb_videomode * <parameter>mode1</parameter></paramdef>
   <paramdef>const struct fb_videomode * <parameter>mode2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode1</parameter></term>
   <listitem>
    <para>
     first videomode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode2</parameter></term>
   <listitem>
    <para>
     second videomode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   1 if equal, 0 if not
</para>
</refsect1>
</refentry>

<refentry id="API-fb-find-best-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_find_best_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_find_best_mode</refname>
 <refpurpose>
     find best matching videomode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct fb_videomode * <function>fb_find_best_mode </function></funcdef>
   <paramdef>const struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_var_screeninfo
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     pointer to struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   struct fb_videomode, NULL if none found
</para>
</refsect1>
<refsect1>
<title>IMPORTANT</title>
<para>
   This function assumes that all modelist entries in
   info-&gt;modelist are valid.
</para>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   Finds best matching videomode which has an equal or greater dimension than
   var-&gt;xres and var-&gt;yres.  If more than 1 videomode is found, will return
   the videomode with the highest refresh rate
</para>
</refsect1>
</refentry>

<refentry id="API-fb-find-nearest-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_find_nearest_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_find_nearest_mode</refname>
 <refpurpose>
     find closest videomode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct fb_videomode * <function>fb_find_nearest_mode </function></funcdef>
   <paramdef>const struct fb_videomode * <parameter>mode</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_videomode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     pointer to modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds best matching videomode, smaller or greater in dimension.
   If more than 1 videomode is found, will return the videomode with
   the closest refresh rate.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-match-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_match_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_match_mode</refname>
 <refpurpose>
     find a videomode which exactly matches the timings in var
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct fb_videomode * <function>fb_match_mode </function></funcdef>
   <paramdef>const struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_var_screeninfo
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     pointer to struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   struct fb_videomode, NULL if none found
</para>
</refsect1>
</refentry>

<refentry id="API-fb-add-videomode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_add_videomode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_add_videomode</refname>
 <refpurpose>
     adds videomode entry to modelist
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_add_videomode </function></funcdef>
   <paramdef>const struct fb_videomode * <parameter>mode</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     videomode to add
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   Will only add unmatched mode entries
</para>
</refsect1>
</refentry>

<refentry id="API-fb-destroy-modelist">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_destroy_modelist</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_destroy_modelist</refname>
 <refpurpose>
     destroy modelist
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_destroy_modelist </function></funcdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-fb-videomode-to-modelist">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_videomode_to_modelist</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_videomode_to_modelist</refname>
 <refpurpose>
     convert mode array to mode list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_videomode_to_modelist </function></funcdef>
   <paramdef>const struct fb_videomode * <parameter>modedb</parameter></paramdef>
   <paramdef>int <parameter>num</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>modedb</parameter></term>
   <listitem>
    <para>
     array of struct fb_videomode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num</parameter></term>
   <listitem>
    <para>
     number of entries in array
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Frame Buffer Macintosh Video Mode Database</title>
<!-- drivers/video/fbdev/macmodes.c -->
<refentry id="API-mac-vmode-to-var">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mac_vmode_to_var</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mac_vmode_to_var</refname>
 <refpurpose>
  converts vmode/cmode pair to var structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mac_vmode_to_var </function></funcdef>
   <paramdef>int <parameter>vmode</parameter></paramdef>
   <paramdef>int <parameter>cmode</parameter></paramdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vmode</parameter></term>
   <listitem>
    <para>
     MacOS video mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmode</parameter></term>
   <listitem>
    <para>
     MacOS color mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     frame buffer video mode structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Converts a MacOS vmode/cmode pair to a frame buffer video
   mode structure.
   </para><para>

   Returns negative errno on error, or zero for success.
</para>
</refsect1>
</refentry>

<refentry id="API-mac-map-monitor-sense">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mac_map_monitor_sense</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mac_map_monitor_sense</refname>
 <refpurpose>
     Convert monitor sense to vmode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mac_map_monitor_sense </function></funcdef>
   <paramdef>int <parameter>sense</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sense</parameter></term>
   <listitem>
    <para>
     Macintosh monitor sense number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Converts a Macintosh monitor sense number to a MacOS
   vmode number.
   </para><para>

   Returns MacOS vmode video mode number.
</para>
</refsect1>
</refentry>

<refentry id="API-mac-find-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mac_find_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mac_find_mode</refname>
 <refpurpose>
     find a video mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mac_find_mode </function></funcdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const char * <parameter>mode_option</parameter></paramdef>
   <paramdef>unsigned int <parameter>default_bpp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     frame buffer user defined part of display
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode_option</parameter></term>
   <listitem>
    <para>
     video mode name (see mac_modedb[])
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>default_bpp</parameter></term>
   <listitem>
    <para>
     default color depth in bits per pixel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds a suitable video mode.  Tries to set mode specified
   by <parameter>mode_option</parameter>.  If the name of the wanted mode begins with
   'mac', the Mac video mode database will be used, otherwise it
   will fall back to the standard video mode database.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   Function marked as __init and can only be used during
   system boot.
   </para><para>

   Returns error code from fb_find_mode (see fb_find_mode
   function).
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Frame Buffer Fonts</title>
        <para>
           Refer to the file lib/fonts/fonts.c for more information.
        </para>
<!-- FIXME: Removed for now since no structured comments in source
X!Ilib/fonts/fonts.c
-->
     </sect1>
  </chapter>

  <chapter id="input_subsystem">
     <title>Input Subsystem</title>
     <sect1><title>Input core</title>
<!-- include/linux/input.h -->
<refentry id="API-struct-input-value">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct input_value</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct input_value</refname>
 <refpurpose>
  input value representation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct input_value {
  __u16 type;
  __u16 code;
  __s32 value;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>type</term>
      <listitem><para>
type of value (EV_KEY, EV_ABS, etc)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>code</term>
      <listitem><para>
the value code
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>value</term>
      <listitem><para>
the value
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-input-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct input_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct input_dev</refname>
 <refpurpose>
     represents an input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct input_dev {
  const char * name;
  const char * phys;
  const char * uniq;
  struct input_id id;
  unsigned long propbit[BITS_TO_LONGS(INPUT_PROP_CNT)];
  unsigned long evbit[BITS_TO_LONGS(EV_CNT)];
  unsigned long keybit[BITS_TO_LONGS(KEY_CNT)];
  unsigned long relbit[BITS_TO_LONGS(REL_CNT)];
  unsigned long absbit[BITS_TO_LONGS(ABS_CNT)];
  unsigned long mscbit[BITS_TO_LONGS(MSC_CNT)];
  unsigned long ledbit[BITS_TO_LONGS(LED_CNT)];
  unsigned long sndbit[BITS_TO_LONGS(SND_CNT)];
  unsigned long ffbit[BITS_TO_LONGS(FF_CNT)];
  unsigned long swbit[BITS_TO_LONGS(SW_CNT)];
  unsigned int hint_events_per_packet;
  unsigned int keycodemax;
  unsigned int keycodesize;
  void * keycode;
  int (* setkeycode) (struct input_dev *dev,const struct input_keymap_entry *ke,unsigned int *old_keycode);
  int (* getkeycode) (struct input_dev *dev,struct input_keymap_entry *ke);
  struct ff_device * ff;
  unsigned int repeat_key;
  struct timer_list timer;
  int rep[REP_CNT];
  struct input_mt * mt;
  struct input_absinfo * absinfo;
  unsigned long key[BITS_TO_LONGS(KEY_CNT)];
  unsigned long led[BITS_TO_LONGS(LED_CNT)];
  unsigned long snd[BITS_TO_LONGS(SND_CNT)];
  unsigned long sw[BITS_TO_LONGS(SW_CNT)];
  int (* open) (struct input_dev *dev);
  void (* close) (struct input_dev *dev);
  int (* flush) (struct input_dev *dev, struct file *file);
  int (* event) (struct input_dev *dev, unsigned int type, unsigned int code, int value);
  struct input_handle __rcu * grab;
  spinlock_t event_lock;
  struct mutex mutex;
  unsigned int users;
  bool going_away;
  struct device dev;
  struct list_head h_list;
  struct list_head node;
  unsigned int num_vals;
  unsigned int max_vals;
  struct input_value * vals;
  bool devres_managed;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name</term>
      <listitem><para>
   name of the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>phys</term>
      <listitem><para>
   physical path to the device in the system hierarchy
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>uniq</term>
      <listitem><para>
   unique identification code for the device (if device has it)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id</term>
      <listitem><para>
   id of the device (struct input_id)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>propbit[BITS_TO_LONGS(INPUT_PROP_CNT)]</term>
      <listitem><para>
   bitmap of device properties and quirks
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>evbit[BITS_TO_LONGS(EV_CNT)]</term>
      <listitem><para>
   bitmap of types of events supported by the device (EV_KEY,
   EV_REL, etc.)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>keybit[BITS_TO_LONGS(KEY_CNT)]</term>
      <listitem><para>
   bitmap of keys/buttons this device has
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>relbit[BITS_TO_LONGS(REL_CNT)]</term>
      <listitem><para>
   bitmap of relative axes for the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>absbit[BITS_TO_LONGS(ABS_CNT)]</term>
      <listitem><para>
   bitmap of absolute axes for the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mscbit[BITS_TO_LONGS(MSC_CNT)]</term>
      <listitem><para>
   bitmap of miscellaneous events supported by the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ledbit[BITS_TO_LONGS(LED_CNT)]</term>
      <listitem><para>
   bitmap of leds present on the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sndbit[BITS_TO_LONGS(SND_CNT)]</term>
      <listitem><para>
   bitmap of sound effects supported by the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ffbit[BITS_TO_LONGS(FF_CNT)]</term>
      <listitem><para>
   bitmap of force feedback effects supported by the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>swbit[BITS_TO_LONGS(SW_CNT)]</term>
      <listitem><para>
   bitmap of switches present on the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>hint_events_per_packet</term>
      <listitem><para>
   average number of events generated by the
   device in a packet (between EV_SYN/SYN_REPORT events). Used by
   event handlers to estimate size of the buffer needed to hold
   events.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>keycodemax</term>
      <listitem><para>
   size of keycode table
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>keycodesize</term>
      <listitem><para>
   size of elements in keycode table
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>keycode</term>
      <listitem><para>
   map of scancodes to keycodes for this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>setkeycode</term>
      <listitem><para>
   optional method to alter current keymap, used to implement
   sparse keymaps. If not supplied default mechanism will be used.
   The method is being called while holding event_lock and thus must
   not sleep
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>getkeycode</term>
      <listitem><para>
   optional legacy method to retrieve current keymap.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ff</term>
      <listitem><para>
   force feedback structure associated with the device if device
   supports force feedback effects
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>repeat_key</term>
      <listitem><para>
   stores key code of the last key pressed; used to implement
   software autorepeat
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>timer</term>
      <listitem><para>
   timer for software autorepeat
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rep[REP_CNT]</term>
      <listitem><para>
   current values for autorepeat parameters (delay, rate)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mt</term>
      <listitem><para>
   pointer to multitouch state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>absinfo</term>
      <listitem><para>
   array of <structname>struct input_absinfo</structname> elements holding information
   about absolute axes (current value, min, max, flat, fuzz,
   resolution)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>key[BITS_TO_LONGS(KEY_CNT)]</term>
      <listitem><para>
   reflects current state of device's keys/buttons
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>led[BITS_TO_LONGS(LED_CNT)]</term>
      <listitem><para>
   reflects current state of device's LEDs
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>snd[BITS_TO_LONGS(SND_CNT)]</term>
      <listitem><para>
   reflects current state of sound effects
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sw[BITS_TO_LONGS(SW_CNT)]</term>
      <listitem><para>
   reflects current state of device's switches
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>open</term>
      <listitem><para>
   this method is called when the very first user calls
   <function><link linkend="API-input-open-device">input_open_device</link></function>. The driver must prepare the device
   to start generating events (start polling thread,
   request an IRQ, submit URB, etc.)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>close</term>
      <listitem><para>
   this method is called when the very last user calls
   <function><link linkend="API-input-close-device">input_close_device</link></function>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flush</term>
      <listitem><para>
   purges the device. Most commonly used to get rid of force
   feedback effects loaded into the device when disconnecting
   from it
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>event</term>
      <listitem><para>
   event handler for events sent _to_ the device, like EV_LED
   or EV_SND. The device is expected to carry out the requested
   action (turn on a LED, play sound, etc.) The call is protected
   by <parameter>event_lock</parameter> and must not sleep
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>grab</term>
      <listitem><para>
   input handle that currently has the device grabbed (via
   EVIOCGRAB ioctl). When a handle grabs a device it becomes sole
   recipient for all input events coming from the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>event_lock</term>
      <listitem><para>
   this spinlock is is taken when input core receives
   and processes a new event for the device (in <function><link linkend="API-input-event">input_event</link></function>).
   Code that accesses and/or modifies parameters of a device
   (such as keymap or absmin, absmax, absfuzz, etc.) after device
   has been registered with input core must take this lock.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mutex</term>
      <listitem><para>
   serializes calls to <function>open</function>, <function>close</function> and <function>flush</function> methods
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>users</term>
      <listitem><para>
   stores number of users (input handlers) that opened this
   device. It is used by <function><link linkend="API-input-open-device">input_open_device</link></function> and <function><link linkend="API-input-close-device">input_close_device</link></function>
   to make sure that dev-&gt;<function>open</function> is only called when the first
   user opens device and dev-&gt;<function>close</function> is called when the very
   last user closes the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>going_away</term>
      <listitem><para>
   marks devices that are in a middle of unregistering and
   causes input_open_device*() fail with -ENODEV.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   driver model's view of this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>h_list</term>
      <listitem><para>
   list of input handles associated with the device. When
   accessing the list dev-&gt;mutex must be held
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>node</term>
      <listitem><para>
   used to place the device onto input_dev_list
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_vals</term>
      <listitem><para>
   number of values queued in the current frame
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_vals</term>
      <listitem><para>
   maximum number of values queued in a frame
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>vals</term>
      <listitem><para>
   array of values queued in the current frame
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>devres_managed</term>
      <listitem><para>
   indicates that devices is managed with devres framework
   and needs not be explicitly unregistered or freed.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-input-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct input_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct input_handler</refname>
 <refpurpose>
     implements one of interfaces for input devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct input_handler {
  void * private;
  void (* event) (struct input_handle *handle, unsigned int type, unsigned int code, int value);
  void (* events) (struct input_handle *handle,const struct input_value *vals, unsigned int count);
  bool (* filter) (struct input_handle *handle, unsigned int type, unsigned int code, int value);
  bool (* match) (struct input_handler *handler, struct input_dev *dev);
  int (* connect) (struct input_handler *handler, struct input_dev *dev, const struct input_device_id *id);
  void (* disconnect) (struct input_handle *handle);
  void (* start) (struct input_handle *handle);
  bool legacy_minors;
  int minor;
  const char * name;
  const struct input_device_id * id_table;
  struct list_head h_list;
  struct list_head node;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>private</term>
      <listitem><para>
   driver-specific data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>event</term>
      <listitem><para>
   event handler. This method is being called by input core with
   interrupts disabled and dev-&gt;event_lock spinlock held and so
   it may not sleep
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>events</term>
      <listitem><para>
   event sequence handler. This method is being called by
   input core with interrupts disabled and dev-&gt;event_lock
   spinlock held and so it may not sleep
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>filter</term>
      <listitem><para>
   similar to <parameter>event</parameter>; separates normal event handlers from
   <quote>filters</quote>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>match</term>
      <listitem><para>
   called after comparing device's id with handler's id_table
   to perform fine-grained matching between device and handler
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connect</term>
      <listitem><para>
   called when attaching a handler to an input device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>disconnect</term>
      <listitem><para>
   disconnects a handler from input device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start</term>
      <listitem><para>
   starts handler for given handle. This function is called by
   input core right after <function>connect</function> method and also when a process
   that <quote>grabbed</quote> a device releases it
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>legacy_minors</term>
      <listitem><para>
   set to <constant>true</constant> by drivers using legacy minor ranges
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>minor</term>
      <listitem><para>
   beginning of range of 32 legacy minors for devices this driver
   can provide
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name</term>
      <listitem><para>
   name of the handler, to be shown in /proc/bus/input/handlers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id_table</term>
      <listitem><para>
   pointer to a table of input_device_ids this driver can
   handle
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>h_list</term>
      <listitem><para>
   list of input handles associated with the handler
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>node</term>
      <listitem><para>
   for placing the driver onto input_handler_list
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Input handlers attach to input devices and create input handles. There
   are likely several handlers attached to any given input device at the
   same time. All of them will get their copy of input event generated by
   the device.
   </para><para>

   The very same structure is used to implement input filters. Input core
   allows filters to run first and will not pass event to regular handlers
   if any of the filters indicate that the event should be filtered (by
   returning <constant>true</constant> from their <function>filter</function> method).
   </para><para>

   Note that input core serializes calls to <function>connect</function> and <function>disconnect</function>
   methods.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-input-handle">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct input_handle</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct input_handle</refname>
 <refpurpose>
     links input device with an input handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct input_handle {
  void * private;
  int open;
  const char * name;
  struct input_dev * dev;
  struct input_handler * handler;
  struct list_head d_node;
  struct list_head h_node;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>private</term>
      <listitem><para>
   handler-specific data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>open</term>
      <listitem><para>
   counter showing whether the handle is 'open', i.e. should deliver
   events from its device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name</term>
      <listitem><para>
   name given to the handle by handler that created it
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   input device the handle is attached to
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>handler</term>
      <listitem><para>
   handler that works with the device through this handle
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>d_node</term>
      <listitem><para>
   used to put the handle on device's list of attached handles
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>h_node</term>
      <listitem><para>
   used to put the handle on handler's list of handles from which
   it gets events
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-input-set-events-per-packet">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_set_events_per_packet</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_set_events_per_packet</refname>
 <refpurpose>
     tell handlers about the driver event rate
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_set_events_per_packet </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>n_events</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the input device used by the driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n_events</parameter></term>
   <listitem>
    <para>
     the average number of events between calls to <function>input_sync</function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the event rate sent from a device is unusually large, use this
   function to set the expected event rate. This will allow handlers
   to set up an appropriate buffer size for the event stream, in order
   to minimize information loss.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-ff-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct ff_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct ff_device</refname>
 <refpurpose>
     force-feedback part of an input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct ff_device {
  int (* upload) (struct input_dev *dev, struct ff_effect *effect,struct ff_effect *old);
  int (* erase) (struct input_dev *dev, int effect_id);
  int (* playback) (struct input_dev *dev, int effect_id, int value);
  void (* set_gain) (struct input_dev *dev, u16 gain);
  void (* set_autocenter) (struct input_dev *dev, u16 magnitude);
  void (* destroy) (struct ff_device *);
  void * private;
  unsigned long ffbit[BITS_TO_LONGS(FF_CNT)];
  struct mutex mutex;
  int max_effects;
  struct ff_effect * effects;
  struct file * effect_owners[];
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>upload</term>
      <listitem><para>
   Called to upload an new effect into device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>erase</term>
      <listitem><para>
   Called to erase an effect from device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>playback</term>
      <listitem><para>
   Called to request device to start playing specified effect
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_gain</term>
      <listitem><para>
   Called to set specified gain
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_autocenter</term>
      <listitem><para>
   Called to auto-center device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>destroy</term>
      <listitem><para>
   called by input core when parent input device is being
   destroyed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>private</term>
      <listitem><para>
   driver-specific data, will be freed automatically
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ffbit[BITS_TO_LONGS(FF_CNT)]</term>
      <listitem><para>
   bitmap of force feedback capabilities truly supported by
   device (not emulated like ones in input_dev-&gt;ffbit)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mutex</term>
      <listitem><para>
   mutex for serializing access to the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_effects</term>
      <listitem><para>
   maximum number of effects supported by device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>effects</term>
      <listitem><para>
   pointer to an array of effects currently loaded into device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>effect_owners[]</term>
      <listitem><para>
   array of effect owners; when file handle owning
   an effect gets closed the effect is automatically erased
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Every force-feedback device must implement <function>upload</function> and <function>playback</function>
   methods; <function>erase</function> is optional. <function>set_gain</function> and <function>set_autocenter</function> need
   only be implemented if driver sets up FF_GAIN and FF_AUTOCENTER
   bits.
   </para><para>

   Note that <function>playback</function>, <function>set_gain</function> and <function>set_autocenter</function> are called with
   dev-&gt;event_lock spinlock held and interrupts off and thus may not
   sleep.
</para>
</refsect1>
</refentry>

<!-- drivers/input/input.c -->
<refentry id="API-input-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_event</refname>
 <refpurpose>
  report new input event
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_event </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>type</parameter></paramdef>
   <paramdef>unsigned int <parameter>code</parameter></paramdef>
   <paramdef>int <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device that generated the event
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of the event
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>code</parameter></term>
   <listitem>
    <para>
     event code
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     value of the event
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should be used by drivers implementing various input
   devices to report input events. See also <function><link linkend="API-input-inject-event">input_inject_event</link></function>.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   <function><link linkend="API-input-event">input_event</link></function> may be safely used right after input device was
   allocated with <function><link linkend="API-input-allocate-device">input_allocate_device</link></function>, even before it is registered
   with <function><link linkend="API-input-register-device">input_register_device</link></function>, but the event will not reach any of the
   input handlers. Such early invocation of <function><link linkend="API-input-event">input_event</link></function> may be used
   to 'seed' initial state of a switch or initial position of absolute
   axis, etc.
</para>
</refsect1>
</refentry>

<refentry id="API-input-inject-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_inject_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_inject_event</refname>
 <refpurpose>
     send input event from input handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_inject_event </function></funcdef>
   <paramdef><link linkend="API-struct-input-handle">struct input_handle</link> * <parameter>handle</parameter></paramdef>
   <paramdef>unsigned int <parameter>type</parameter></paramdef>
   <paramdef>unsigned int <parameter>code</parameter></paramdef>
   <paramdef>int <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     input handle to send event through
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of the event
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>code</parameter></term>
   <listitem>
    <para>
     event code
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     value of the event
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Similar to <function><link linkend="API-input-event">input_event</link></function> but will ignore event if device is
   <quote>grabbed</quote> and handle injecting event is not the one that owns
   the device.
</para>
</refsect1>
</refentry>

<refentry id="API-input-alloc-absinfo">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_alloc_absinfo</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_alloc_absinfo</refname>
 <refpurpose>
     allocates array of input_absinfo structs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_alloc_absinfo </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the input device emitting absolute events
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the absinfo struct the caller asked for is already allocated, this
   functions will not do anything.
</para>
</refsect1>
</refentry>

<refentry id="API-input-grab-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_grab_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_grab_device</refname>
 <refpurpose>
     grabs device for exclusive use
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_grab_device </function></funcdef>
   <paramdef><link linkend="API-struct-input-handle">struct input_handle</link> * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     input handle that wants to own the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When a device is grabbed by an input handle all events generated by
   the device are delivered only to this handle. Also events injected
   by other input handles are ignored while device is grabbed.
</para>
</refsect1>
</refentry>

<refentry id="API-input-release-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_release_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_release_device</refname>
 <refpurpose>
     release previously grabbed device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_release_device </function></funcdef>
   <paramdef><link linkend="API-struct-input-handle">struct input_handle</link> * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     input handle that owns the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases previously grabbed device so that other input handles can
   start receiving input events. Upon release all handlers attached
   to the device have their <function>start</function> method called so they have a change
   to synchronize device state with the rest of the system.
</para>
</refsect1>
</refentry>

<refentry id="API-input-open-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_open_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_open_device</refname>
 <refpurpose>
     open input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_open_device </function></funcdef>
   <paramdef><link linkend="API-struct-input-handle">struct input_handle</link> * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     handle through which device is being accessed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should be called by input handlers when they
   want to start receive events from given input device.
</para>
</refsect1>
</refentry>

<refentry id="API-input-close-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_close_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_close_device</refname>
 <refpurpose>
     close input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_close_device </function></funcdef>
   <paramdef><link linkend="API-struct-input-handle">struct input_handle</link> * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     handle through which device is being accessed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should be called by input handlers when they
   want to stop receive events from given input device.
</para>
</refsect1>
</refentry>

<refentry id="API-input-scancode-to-scalar">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_scancode_to_scalar</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_scancode_to_scalar</refname>
 <refpurpose>
     converts scancode in <structname>struct input_keymap_entry</structname>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_scancode_to_scalar </function></funcdef>
   <paramdef>const struct input_keymap_entry * <parameter>ke</parameter></paramdef>
   <paramdef>unsigned int * <parameter>scancode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ke</parameter></term>
   <listitem>
    <para>
     keymap entry containing scancode to be converted.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>scancode</parameter></term>
   <listitem>
    <para>
     pointer to the location where converted scancode should
     be stored.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is used to convert scancode stored in <structname>struct keymap_entry</structname>
   into scalar form understood by legacy keymap handling methods. These
   methods expect scancodes to be represented as 'unsigned int'.
</para>
</refsect1>
</refentry>

<refentry id="API-input-get-keycode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_get_keycode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_get_keycode</refname>
 <refpurpose>
     retrieve keycode currently mapped to a given scancode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_get_keycode </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>struct input_keymap_entry * <parameter>ke</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device which keymap is being queried
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ke</parameter></term>
   <listitem>
    <para>
     keymap entry
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should be called by anyone interested in retrieving current
   keymap. Presently evdev handlers use it.
</para>
</refsect1>
</refentry>

<refentry id="API-input-set-keycode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_set_keycode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_set_keycode</refname>
 <refpurpose>
     attribute a keycode to a given scancode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_set_keycode </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const struct input_keymap_entry * <parameter>ke</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device which keymap is being updated
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ke</parameter></term>
   <listitem>
    <para>
     new keymap entry
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should be called by anyone needing to update current
   keymap. Presently keyboard and evdev handlers use it.
</para>
</refsect1>
</refentry>

<refentry id="API-input-reset-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_reset_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_reset_device</refname>
 <refpurpose>
     reset/restore the state of input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_reset_device </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device whose state needs to be reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function tries to reset the state of an opened input device and
   bring internal state and state if the hardware in sync with each other.
   We mark all keys as released, restore LED state, repeat rate, etc.
</para>
</refsect1>
</refentry>

<refentry id="API-input-allocate-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_allocate_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_allocate_device</refname>
 <refpurpose>
     allocate memory for new input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-input-dev">struct input_dev</link> * <function>input_allocate_device </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns prepared struct input_dev or <constant>NULL</constant>.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   Use <function><link linkend="API-input-free-device">input_free_device</link></function> to free devices that have not been
   registered; <function><link linkend="API-input-unregister-device">input_unregister_device</link></function> should be used for already
   registered devices.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-input-allocate-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_input_allocate_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_input_allocate_device</refname>
 <refpurpose>
     allocate managed input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-input-dev">struct input_dev</link> * <function>devm_input_allocate_device </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device owning the input device being created
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns prepared struct input_dev or <constant>NULL</constant>.
   </para><para>

   Managed input devices do not need to be explicitly unregistered or
   freed as it will be done automatically when owner device unbinds from
   its driver (or binding fails). Once managed input device is allocated,
   it is ready to be set up and registered in the same fashion as regular
   input device. There are no special devm_input_device_[un]<function>register</function>
   variants, regular ones work with both managed and unmanaged devices,
   should you need them. In most cases however, managed input device need
   not be explicitly unregistered or freed.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   the owner device is set up as parent of input device and users
   should not override it.
</para>
</refsect1>
</refentry>

<refentry id="API-input-free-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_free_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_free_device</refname>
 <refpurpose>
     free memory occupied by input_dev structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_free_device </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should only be used if <function><link linkend="API-input-register-device">input_register_device</link></function>
   was not called yet or if it failed. Once device was registered
   use <function><link linkend="API-input-unregister-device">input_unregister_device</link></function> and memory will be freed once last
   reference to the device is dropped.
   </para><para>

   Device should be allocated by <function><link linkend="API-input-allocate-device">input_allocate_device</link></function>.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   If there are references to the input device then memory
   will not be freed until last reference is dropped.
</para>
</refsect1>
</refentry>

<refentry id="API-input-set-capability">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_set_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_set_capability</refname>
 <refpurpose>
     mark device as capable of a certain event
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_set_capability </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>type</parameter></paramdef>
   <paramdef>unsigned int <parameter>code</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device that is capable of emitting or accepting event
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of the event (EV_KEY, EV_REL, etc...)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>code</parameter></term>
   <listitem>
    <para>
     event code
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   In addition to setting up corresponding bit in appropriate capability
   bitmap the function also adjusts dev-&gt;evbit.
</para>
</refsect1>
</refentry>

<refentry id="API-input-enable-softrepeat">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_enable_softrepeat</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_enable_softrepeat</refname>
 <refpurpose>
     enable software autorepeat
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_enable_softrepeat </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>delay</parameter></paramdef>
   <paramdef>int <parameter>period</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delay</parameter></term>
   <listitem>
    <para>
     repeat delay
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>period</parameter></term>
   <listitem>
    <para>
     repeat period
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enable software autorepeat on the input device.
</para>
</refsect1>
</refentry>

<refentry id="API-input-register-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_register_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_register_device</refname>
 <refpurpose>
     register device with input core
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_register_device </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to be registered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function registers device with input core. The device must be
   allocated with <function><link linkend="API-input-allocate-device">input_allocate_device</link></function> and all it's capabilities
   set up before registering.
   If function fails the device must be freed with <function><link linkend="API-input-free-device">input_free_device</link></function>.
   Once device has been successfully registered it can be unregistered
   with <function><link linkend="API-input-unregister-device">input_unregister_device</link></function>; <function><link linkend="API-input-free-device">input_free_device</link></function> should not be
   called in this case.
   </para><para>

   Note that this function is also used to register managed input devices
   (ones allocated with <function><link linkend="API-devm-input-allocate-device">devm_input_allocate_device</link></function>). Such managed input
   devices need not be explicitly unregistered or freed, their tear down
   is controlled by the devres infrastructure. It is also worth noting
   that tear down of managed input devices is internally a 2-step process:
   registered managed input device is first unregistered, but stays in
   memory and can still handle <function><link linkend="API-input-event">input_event</link></function> calls (although events will
   not be delivered anywhere). The freeing of managed input device will
   happen later, when devres stack is unwound to the point where device
   allocation was made.
</para>
</refsect1>
</refentry>

<refentry id="API-input-unregister-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_unregister_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_unregister_device</refname>
 <refpurpose>
     unregister previously registered device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_unregister_device </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to be unregistered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function unregisters an input device. Once device is unregistered
   the caller should not try to access it as it may get freed at any moment.
</para>
</refsect1>
</refentry>

<refentry id="API-input-register-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_register_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_register_handler</refname>
 <refpurpose>
     register a new input handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_register_handler </function></funcdef>
   <paramdef><link linkend="API-struct-input-handler">struct input_handler</link> * <parameter>handler</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
     handler to be registered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function registers a new input handler (interface) for input
   devices in the system and attaches it to all input devices that
   are compatible with the handler.
</para>
</refsect1>
</refentry>

<refentry id="API-input-unregister-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_unregister_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_unregister_handler</refname>
 <refpurpose>
     unregisters an input handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_unregister_handler </function></funcdef>
   <paramdef><link linkend="API-struct-input-handler">struct input_handler</link> * <parameter>handler</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
     handler to be unregistered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function disconnects a handler from its input devices and
   removes it from lists of known handlers.
</para>
</refsect1>
</refentry>

<refentry id="API-input-handler-for-each-handle">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_handler_for_each_handle</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_handler_for_each_handle</refname>
 <refpurpose>
     handle iterator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_handler_for_each_handle </function></funcdef>
   <paramdef><link linkend="API-struct-input-handler">struct input_handler</link> * <parameter>handler</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>fn</parameter>)
     <funcparams>struct input_handle *, void *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
     input handler to iterate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data for the callback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     function to be called for each handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over <parameter>bus</parameter>'s list of devices, and call <parameter>fn</parameter> for each, passing
   it <parameter>data</parameter> and stop when <parameter>fn</parameter> returns a non-zero value. The function is
   using RCU to traverse the list and therefore may be using in atomic
   contexts. The <parameter>fn</parameter> callback is invoked from RCU critical section and
   thus must not sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-input-register-handle">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_register_handle</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_register_handle</refname>
 <refpurpose>
     register a new input handle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_register_handle </function></funcdef>
   <paramdef><link linkend="API-struct-input-handle">struct input_handle</link> * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     handle to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function puts a new input handle onto device's
   and handler's lists so that events can flow through
   it once it is opened using <function><link linkend="API-input-open-device">input_open_device</link></function>.
   </para><para>

   This function is supposed to be called from handler's
   <function>connect</function> method.
</para>
</refsect1>
</refentry>

<refentry id="API-input-unregister-handle">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_unregister_handle</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_unregister_handle</refname>
 <refpurpose>
     unregister an input handle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_unregister_handle </function></funcdef>
   <paramdef><link linkend="API-struct-input-handle">struct input_handle</link> * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     handle to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function removes input handle from device's
   and handler's lists.
   </para><para>

   This function is supposed to be called from handler's
   <function>disconnect</function> method.
</para>
</refsect1>
</refentry>

<refentry id="API-input-get-new-minor">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_get_new_minor</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_get_new_minor</refname>
 <refpurpose>
     allocates a new input minor number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_get_new_minor </function></funcdef>
   <paramdef>int <parameter>legacy_base</parameter></paramdef>
   <paramdef>unsigned int <parameter>legacy_num</parameter></paramdef>
   <paramdef>bool <parameter>allow_dynamic</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>legacy_base</parameter></term>
   <listitem>
    <para>
     beginning or the legacy range to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>legacy_num</parameter></term>
   <listitem>
    <para>
     size of legacy range
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>allow_dynamic</parameter></term>
   <listitem>
    <para>
     whether we can also take ID from the dynamic range
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function allocates a new device minor for from input major namespace.
   Caller can request legacy minor by specifying <parameter>legacy_base</parameter> and <parameter>legacy_num</parameter>
   parameters and whether ID can be allocated from dynamic range if there are
   no free IDs in legacy range.
</para>
</refsect1>
</refentry>

<refentry id="API-input-free-minor">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_free_minor</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_free_minor</refname>
 <refpurpose>
     release previously allocated minor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_free_minor </function></funcdef>
   <paramdef>unsigned int <parameter>minor</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>minor</parameter></term>
   <listitem>
    <para>
     minor to be released
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function releases previously allocated input minor so that it can be
   reused later.
</para>
</refsect1>
</refentry>

<!-- drivers/input/ff-core.c -->
<refentry id="API-input-ff-upload">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_upload</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_upload</refname>
 <refpurpose>
  upload effect into force-feedback device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_ff_upload </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>struct ff_effect * <parameter>effect</parameter></paramdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>effect</parameter></term>
   <listitem>
    <para>
     effect to be uploaded
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     owner of the effect
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-input-ff-erase">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_erase</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_erase</refname>
 <refpurpose>
     erase a force-feedback effect from device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_ff_erase </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>effect_id</parameter></paramdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device to erase effect from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>effect_id</parameter></term>
   <listitem>
    <para>
     id of the effect to be erased
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     purported owner of the request
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function erases a force-feedback effect from specified device.
   The effect will only be erased if it was uploaded through the same
   file handle that is requesting erase.
</para>
</refsect1>
</refentry>

<refentry id="API-input-ff-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_event</refname>
 <refpurpose>
     generic handler for force-feedback events
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_ff_event </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>type</parameter></paramdef>
   <paramdef>unsigned int <parameter>code</parameter></paramdef>
   <paramdef>int <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device to send the effect to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     event type (anything but EV_FF is ignored)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>code</parameter></term>
   <listitem>
    <para>
     event code
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     event value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-input-ff-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_create</refname>
 <refpurpose>
     create force-feedback device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_ff_create </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>max_effects</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device supporting force-feedback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_effects</parameter></term>
   <listitem>
    <para>
     maximum number of effects supported by the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function allocates all necessary memory for a force feedback
   portion of an input device and installs all default handlers.
   <parameter>dev</parameter>-&gt;ffbit should be already set up before calling this function.
   Once ff device is created you need to setup its upload, erase,
   playback and other handlers before registering input device
</para>
</refsect1>
</refentry>

<refentry id="API-input-ff-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_destroy</refname>
 <refpurpose>
     frees force feedback portion of input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_ff_destroy </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device supporting force feedback
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is only needed in error path as input core will
   automatically free force feedback structures when device is
   destroyed.
</para>
</refsect1>
</refentry>

<!-- drivers/input/ff-memless.c -->
<refentry id="API-input-ff-create-memless">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_create_memless</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_create_memless</refname>
 <refpurpose>
  create memoryless force-feedback device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_ff_create_memless </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>play_effect</parameter>)
     <funcparams>struct input_dev *, void *, struct ff_effect *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device supporting force-feedback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     driver-specific data to be passed into <parameter>play_effect</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>play_effect</parameter></term>
   <listitem>
    <para>
     driver-specific method for playing FF effect
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Multitouch Library</title>
<!-- include/linux/input/mt.h -->
<refentry id="API-struct-input-mt-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct input_mt_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct input_mt_slot</refname>
 <refpurpose>
  represents the state of an input MT slot
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct input_mt_slot {
  int abs[ABS_MT_LAST - ABS_MT_FIRST + 1];
  unsigned int frame;
  unsigned int key;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>abs[ABS_MT_LAST - ABS_MT_FIRST + 1]</term>
      <listitem><para>
holds current values of ABS_MT axes for this slot
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>frame</term>
      <listitem><para>
last frame at which <function><link linkend="API-input-mt-report-slot-state">input_mt_report_slot_state</link></function> was called
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>key</term>
      <listitem><para>
optional driver designation of this slot
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-input-mt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct input_mt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct input_mt</refname>
 <refpurpose>
     state of tracked contacts
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct input_mt {
  int trkid;
  int num_slots;
  int slot;
  unsigned int flags;
  unsigned int frame;
  int * red;
  struct input_mt_slot slots[];
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>trkid</term>
      <listitem><para>
   stores MT tracking ID for the next contact
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_slots</term>
      <listitem><para>
   number of MT slots the device uses
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>slot</term>
      <listitem><para>
   MT slot currently being transmitted
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   input_mt operation flags
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>frame</term>
      <listitem><para>
   increases every time <function><link linkend="API-input-mt-sync-frame">input_mt_sync_frame</link></function> is called
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>red</term>
      <listitem><para>
   reduced cost matrix for in-kernel tracking
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>slots[]</term>
      <listitem><para>
   array of slots holding current values of tracked contacts
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-input-mt-pos">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct input_mt_pos</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct input_mt_pos</refname>
 <refpurpose>
     contact position
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct input_mt_pos {
  s16 x;
  s16 y;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>x</term>
      <listitem><para>
   horizontal coordinate
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>y</term>
      <listitem><para>
   vertical coordinate
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- drivers/input/input-mt.c -->
<refentry id="API-input-mt-init-slots">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_mt_init_slots</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_mt_init_slots</refname>
 <refpurpose>
  initialize MT input slots
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_mt_init_slots </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>num_slots</parameter></paramdef>
   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device supporting MT events and finger tracking
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_slots</parameter></term>
   <listitem>
    <para>
     number of slots used by the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     mt tasks to handle in core
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function allocates all necessary memory for MT slot handling
   in the input device, prepares the ABS_MT_SLOT and
   ABS_MT_TRACKING_ID events for use and sets up appropriate buffers.
   Depending on the flags set, it also performs pointer emulation and
   frame synchronization.
   </para><para>

   May be called repeatedly. Returns -EINVAL if attempting to
   reinitialize with a different number of slots.
</para>
</refsect1>
</refentry>

<refentry id="API-input-mt-destroy-slots">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_mt_destroy_slots</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_mt_destroy_slots</refname>
 <refpurpose>
     frees the MT slots of the input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_mt_destroy_slots </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device with allocated MT slots
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is only needed in error path as the input core will
   automatically free the MT slots when the device is destroyed.
</para>
</refsect1>
</refentry>

<refentry id="API-input-mt-report-slot-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_mt_report_slot_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_mt_report_slot_state</refname>
 <refpurpose>
     report contact state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_mt_report_slot_state </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>tool_type</parameter></paramdef>
   <paramdef>bool <parameter>active</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device with allocated MT slots
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tool_type</parameter></term>
   <listitem>
    <para>
     the tool type to use in this slot
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>active</parameter></term>
   <listitem>
    <para>
     true if contact is active, false otherwise
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reports a contact via ABS_MT_TRACKING_ID, and optionally
   ABS_MT_TOOL_TYPE. If active is true and the slot is currently
   inactive, or if the tool type is changed, a new tracking id is
   assigned to the slot. The tool type is only reported if the
   corresponding absbit field is set.
</para>
</refsect1>
</refentry>

<refentry id="API-input-mt-report-finger-count">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_mt_report_finger_count</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_mt_report_finger_count</refname>
 <refpurpose>
     report contact count
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_mt_report_finger_count </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device with allocated MT slots
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of contacts
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reports the contact count via BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP,
   BTN_TOOL_TRIPLETAP and BTN_TOOL_QUADTAP.
   </para><para>

   The input core ensures only the KEY events already setup for
   this device will produce output.
</para>
</refsect1>
</refentry>

<refentry id="API-input-mt-report-pointer-emulation">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_mt_report_pointer_emulation</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_mt_report_pointer_emulation</refname>
 <refpurpose>
     common pointer emulation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_mt_report_pointer_emulation </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>bool <parameter>use_count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device with allocated MT slots
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>use_count</parameter></term>
   <listitem>
    <para>
     report number of active contacts as finger count
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Performs legacy pointer emulation via BTN_TOUCH, ABS_X, ABS_Y and
   ABS_PRESSURE. Touchpad finger count is emulated if use_count is true.
   </para><para>

   The input core ensures only the KEY and ABS axes already setup for
   this device will produce output.
</para>
</refsect1>
</refentry>

<refentry id="API-input-mt-drop-unused">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_mt_drop_unused</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_mt_drop_unused</refname>
 <refpurpose>
     Inactivate slots not seen in this frame
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_mt_drop_unused </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device with allocated MT slots
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Lift all slots not seen since the last call to this function.
</para>
</refsect1>
</refentry>

<refentry id="API-input-mt-sync-frame">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_mt_sync_frame</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_mt_sync_frame</refname>
 <refpurpose>
     synchronize mt frame
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_mt_sync_frame </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device with allocated MT slots
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Close the frame and prepare the internal state for a new one.
   Depending on the flags, marks unused slots as inactive and performs
   pointer emulation.
</para>
</refsect1>
</refentry>

<refentry id="API-input-mt-assign-slots">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_mt_assign_slots</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_mt_assign_slots</refname>
 <refpurpose>
     perform a best-match assignment
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_mt_assign_slots </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>int * <parameter>slots</parameter></paramdef>
   <paramdef><link linkend="API-struct-input-mt-pos">const struct input_mt_pos</link> * <parameter>pos</parameter></paramdef>
   <paramdef>int <parameter>num_pos</parameter></paramdef>
   <paramdef>int <parameter>dmax</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device with allocated MT slots
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>slots</parameter></term>
   <listitem>
    <para>
     the slot assignment to be filled
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the position array to match
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_pos</parameter></term>
   <listitem>
    <para>
     number of positions
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dmax</parameter></term>
   <listitem>
    <para>
     maximum ABS_MT_POSITION displacement (zero for infinite)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Performs a best match against the current contacts and returns
   the slot assignment list. New contacts are assigned to unused
   slots.
   </para><para>

   The assignments are balanced so that all coordinate displacements are
   below the euclidian distance dmax. If no such assignment can be found,
   some contacts are assigned to unused slots.
   </para><para>

   Returns zero on success, or negative error in case of failure.
</para>
</refsect1>
</refentry>

<refentry id="API-input-mt-get-slot-by-key">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_mt_get_slot_by_key</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_mt_get_slot_by_key</refname>
 <refpurpose>
     return slot matching key
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_mt_get_slot_by_key </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>key</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device with allocated MT slots
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>key</parameter></term>
   <listitem>
    <para>
     the key of the sought slot
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the slot of the given key, if it exists, otherwise
   set the key on the first unused slot and return.
   </para><para>

   If no available slot can be found, -1 is returned.
   Note that for this function to work properly, <function><link linkend="API-input-mt-sync-frame">input_mt_sync_frame</link></function> has
   to be called at each frame.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Polled input devices</title>
<!-- include/linux/input-polldev.h -->
<refentry id="API-struct-input-polled-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct input_polled_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct input_polled_dev</refname>
 <refpurpose>
  simple polled input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct input_polled_dev {
  void * private;
  void (* open) (struct input_polled_dev *dev);
  void (* close) (struct input_polled_dev *dev);
  void (* poll) (struct input_polled_dev *dev);
  unsigned int poll_interval;
  unsigned int poll_interval_max;
  unsigned int poll_interval_min;
  struct input_dev * input;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>private</term>
      <listitem><para>
private driver data.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>open</term>
      <listitem><para>
driver-supplied method that prepares device for polling
(enabled the device and maybe flushes device state).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>close</term>
      <listitem><para>
driver-supplied method that is called when device is no
longer being polled. Used to put device into low power mode.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>poll</term>
      <listitem><para>
driver-supplied method that polls the device and posts
input events (mandatory).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>poll_interval</term>
      <listitem><para>
specifies how often the <function>poll</function> method should be called.
Defaults to 500 msec unless overridden when registering the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>poll_interval_max</term>
      <listitem><para>
specifies upper bound for the poll interval.
Defaults to the initial value of <parameter>poll_interval</parameter>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>poll_interval_min</term>
      <listitem><para>
specifies lower bound for the poll interval.
Defaults to 0.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>input</term>
      <listitem><para>
input device structure associated with the polled device.
Must be properly initialized by the driver (id, name, phys, bits).
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Polled input device provides a skeleton for supporting simple input
   devices that do not raise interrupts but have to be periodically
   scanned or polled to detect changes in their state.
</para>
</refsect1>
</refentry>

<!-- drivers/input/input-polldev.c -->
<refentry id="API-input-allocate-polled-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_allocate_polled_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_allocate_polled_device</refname>
 <refpurpose>
  allocate memory for polled device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-input-polled-dev">struct input_polled_dev</link> * <function>input_allocate_polled_device </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   The function allocates memory for a polled device and also
   for an input device associated with this polled device.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-input-allocate-polled-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_input_allocate_polled_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_input_allocate_polled_device</refname>
 <refpurpose>
     allocate managed polled device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-input-polled-dev">struct input_polled_dev</link> * <function>devm_input_allocate_polled_device </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device owning the polled device being created
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns prepared <structname><link linkend="API-struct-input-polled-dev">struct input_polled_dev</link></structname> or <constant>NULL</constant>.
   </para><para>

   Managed polled input devices do not need to be explicitly unregistered
   or freed as it will be done automatically when owner device unbinds
   from * its driver (or binding fails). Once such managed polled device
   is allocated, it is ready to be set up and registered in the same
   fashion as regular polled input devices (using
   <function><link linkend="API-input-register-polled-device">input_register_polled_device</link></function> function).
   </para><para>

   If you want to manually unregister and free such managed polled devices,
   it can be still done by calling <function><link linkend="API-input-unregister-polled-device">input_unregister_polled_device</link></function> and
   <function><link linkend="API-input-free-polled-device">input_free_polled_device</link></function>, although it is rarely needed.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   the owner device is set up as parent of input device and users
   should not override it.
</para>
</refsect1>
</refentry>

<refentry id="API-input-free-polled-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_free_polled_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_free_polled_device</refname>
 <refpurpose>
     free memory allocated for polled device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_free_polled_device </function></funcdef>
   <paramdef><link linkend="API-struct-input-polled-dev">struct input_polled_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The function frees memory allocated for polling device and drops
   reference to the associated input device.
</para>
</refsect1>
</refentry>

<refentry id="API-input-register-polled-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_register_polled_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_register_polled_device</refname>
 <refpurpose>
     register polled device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_register_polled_device </function></funcdef>
   <paramdef><link linkend="API-struct-input-polled-dev">struct input_polled_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The function registers previously initialized polled input device
   with input layer. The device should be allocated with call to
   <function><link linkend="API-input-allocate-polled-device">input_allocate_polled_device</link></function>. Callers should also set up <function>poll</function>
   method and set up capabilities (id, name, phys, bits) of the
   corresponding input_dev structure.
</para>
</refsect1>
</refentry>

<refentry id="API-input-unregister-polled-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_unregister_polled_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_unregister_polled_device</refname>
 <refpurpose>
     unregister polled device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_unregister_polled_device </function></funcdef>
   <paramdef><link linkend="API-struct-input-polled-dev">struct input_polled_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The function unregisters previously registered polled input
   device from input layer. Polling is stopped and device is
   ready to be freed with call to <function><link linkend="API-input-free-polled-device">input_free_polled_device</link></function>.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Matrix keyboars/keypads</title>
<!-- include/linux/input/matrix_keypad.h -->
<refentry id="API-struct-matrix-keymap-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct matrix_keymap_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct matrix_keymap_data</refname>
 <refpurpose>
  keymap for matrix keyboards
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct matrix_keymap_data {
  const uint32_t * keymap;
  unsigned int keymap_size;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>keymap</term>
      <listitem><para>
pointer to array of uint32 values encoded with <function>KEY</function> macro
representing keymap
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>keymap_size</term>
      <listitem><para>
number of entries (initialized) in this keymap
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This structure is supposed to be used by platform code to supply
   keymaps to drivers that implement matrix-like keypads/keyboards.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-matrix-keypad-platform-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct matrix_keypad_platform_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct matrix_keypad_platform_data</refname>
 <refpurpose>
     platform-dependent keypad data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct matrix_keypad_platform_data {
  const struct matrix_keymap_data * keymap_data;
  const unsigned int * row_gpios;
  const unsigned int * col_gpios;
  unsigned int num_row_gpios;
  unsigned int num_col_gpios;
  unsigned int col_scan_delay_us;
  unsigned int debounce_ms;
  unsigned int clustered_irq;
  unsigned int clustered_irq_flags;
  bool active_low;
  bool wakeup;
  bool no_autorepeat;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>keymap_data</term>
      <listitem><para>
   pointer to <structname><link linkend="API-struct-matrix-keymap-data">matrix_keymap_data</link></structname>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>row_gpios</term>
      <listitem><para>
   pointer to array of gpio numbers representing rows
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>col_gpios</term>
      <listitem><para>
   pointer to array of gpio numbers reporesenting colums
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_row_gpios</term>
      <listitem><para>
   actual number of row gpios used by device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_col_gpios</term>
      <listitem><para>
   actual number of col gpios used by device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>col_scan_delay_us</term>
      <listitem><para>
   delay, measured in microseconds, that is
   needed before we can keypad after activating column gpio
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>debounce_ms</term>
      <listitem><para>
   debounce interval in milliseconds
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>clustered_irq</term>
      <listitem><para>
   may be specified if interrupts of all row/column GPIOs
   are bundled to one single irq
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>clustered_irq_flags</term>
      <listitem><para>
   flags that are needed for the clustered irq
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>active_low</term>
      <listitem><para>
   gpio polarity
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>wakeup</term>
      <listitem><para>
   controls whether the device should be set up as wakeup
   source
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>no_autorepeat</term>
      <listitem><para>
   disable key autorepeat
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This structure represents platform-specific data that use used by
   matrix_keypad driver to perform proper initialization.
</para>
</refsect1>
</refentry>

<refentry id="API-matrix-keypad-parse-of-params">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>matrix_keypad_parse_of_params</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>matrix_keypad_parse_of_params</refname>
 <refpurpose>
     Read parameters from matrix-keypad node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>matrix_keypad_parse_of_params </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int * <parameter>rows</parameter></paramdef>
   <paramdef>unsigned int * <parameter>cols</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device containing of_node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rows</parameter></term>
   <listitem>
    <para>
     Returns number of matrix rows
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cols</parameter></term>
   <listitem>
    <para>
     Returns number of matrix columns
     <parameter>return</parameter> 0 if OK, &lt;0 on error
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Sparse keymap support</title>
<!-- include/linux/input/sparse-keymap.h -->
<refentry id="API-struct-key-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct key_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct key_entry</refname>
 <refpurpose>
  keymap entry for use in sparse keymap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct key_entry {
  int type;
  u32 code;
  union {unnamed_union};
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>type</term>
      <listitem><para>
Type of the key entry (KE_KEY, KE_SW, KE_VSW, KE_END);
drivers are allowed to extend the list with their own
private definitions.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>code</term>
      <listitem><para>
Device-specific data identifying the button/switch
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>{unnamed_union}</term>
      <listitem><para>
anonymous
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This structure defines an entry in a sparse keymap used by some
   input devices for which traditional table-based approach is not
   suitable.
</para>
</refsect1>
</refentry>

<!-- drivers/input/sparse-keymap.c -->
<refentry id="API-sparse-keymap-entry-from-scancode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sparse_keymap_entry_from_scancode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sparse_keymap_entry_from_scancode</refname>
 <refpurpose>
  perform sparse keymap lookup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-key-entry">struct key_entry</link> * <function>sparse_keymap_entry_from_scancode </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>code</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Input device using sparse keymap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>code</parameter></term>
   <listitem>
    <para>
     Scan code
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is used to perform <structname><link linkend="API-struct-key-entry">struct key_entry</link></structname> lookup in an
   input device using sparse keymap.
</para>
</refsect1>
</refentry>

<refentry id="API-sparse-keymap-entry-from-keycode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sparse_keymap_entry_from_keycode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sparse_keymap_entry_from_keycode</refname>
 <refpurpose>
     perform sparse keymap lookup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-key-entry">struct key_entry</link> * <function>sparse_keymap_entry_from_keycode </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>keycode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Input device using sparse keymap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>keycode</parameter></term>
   <listitem>
    <para>
     Key code
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is used to perform <structname><link linkend="API-struct-key-entry">struct key_entry</link></structname> lookup in an
   input device using sparse keymap.
</para>
</refsect1>
</refentry>

<refentry id="API-sparse-keymap-setup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sparse_keymap_setup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sparse_keymap_setup</refname>
 <refpurpose>
     set up sparse keymap for an input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sparse_keymap_setup </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef><link linkend="API-struct-key-entry">const struct key_entry</link> * <parameter>keymap</parameter></paramdef>
   <paramdef>int (*<parameter>setup</parameter>)
     <funcparams>struct input_dev *, struct key_entry *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Input device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>keymap</parameter></term>
   <listitem>
    <para>
     Keymap in form of array of <structname><link linkend="API-struct-key-entry">key_entry</link></structname> structures ending
     with <constant>KE_END</constant> type entry
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>setup</parameter></term>
   <listitem>
    <para>
     Function that can be used to adjust keymap entries
     depending on device's deeds, may be <constant>NULL</constant>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The function calculates size and allocates copy of the original
   keymap after which sets up input device event bits appropriately.
   Before destroying input device allocated keymap should be freed
   with a call to <function><link linkend="API-sparse-keymap-free">sparse_keymap_free</link></function>.
</para>
</refsect1>
</refentry>

<refentry id="API-sparse-keymap-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sparse_keymap_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sparse_keymap_free</refname>
 <refpurpose>
     free memory allocated for sparse keymap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sparse_keymap_free </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Input device using sparse keymap
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is used to free memory allocated by sparse keymap
   in an input device that was set up by <function><link linkend="API-sparse-keymap-setup">sparse_keymap_setup</link></function>.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   It is safe to cal this function while input device is
   still registered (however the drivers should care not to try to
   use freed keymap and thus have to shut off interrupts/polling
   before freeing the keymap).
</para>
</refsect1>
</refentry>

<refentry id="API-sparse-keymap-report-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sparse_keymap_report_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sparse_keymap_report_entry</refname>
 <refpurpose>
     report event corresponding to given key entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sparse_keymap_report_entry </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef><link linkend="API-struct-key-entry">const struct key_entry</link> * <parameter>ke</parameter></paramdef>
   <paramdef>unsigned int <parameter>value</parameter></paramdef>
   <paramdef>bool <parameter>autorelease</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Input device for which event should be reported
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ke</parameter></term>
   <listitem>
    <para>
     key entry describing event
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     Value that should be reported (ignored by <constant>KE_SW</constant> entries)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>autorelease</parameter></term>
   <listitem>
    <para>
     Signals whether release event should be emitted for <constant>KE_KEY</constant>
     entries right after reporting press event, ignored by all other
     entries
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is used to report input event described by given
   <structname><link linkend="API-struct-key-entry">struct key_entry</link></structname>.
</para>
</refsect1>
</refentry>

<refentry id="API-sparse-keymap-report-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sparse_keymap_report_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sparse_keymap_report_event</refname>
 <refpurpose>
     report event corresponding to given scancode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>sparse_keymap_report_event </function></funcdef>
   <paramdef><link linkend="API-struct-input-dev">struct input_dev</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>code</parameter></paramdef>
   <paramdef>unsigned int <parameter>value</parameter></paramdef>
   <paramdef>bool <parameter>autorelease</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Input device using sparse keymap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>code</parameter></term>
   <listitem>
    <para>
     Scan code
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     Value that should be reported (ignored by <constant>KE_SW</constant> entries)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>autorelease</parameter></term>
   <listitem>
    <para>
     Signals whether release event should be emitted for <constant>KE_KEY</constant>
     entries right after reporting press event, ignored by all other
     entries
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is used to perform lookup in an input device using sparse
   keymap and report corresponding event. Returns <constant>true</constant> if lookup was
   successful and <constant>false</constant> otherwise.
</para>
</refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="spi">
      <title>Serial Peripheral Interface (SPI)</title>
  <para>
	SPI is the "Serial Peripheral Interface", widely used with
	embedded systems because it is a simple and efficient
	interface:  basically a multiplexed shift register.
	Its three signal wires hold a clock (SCK, often in the range
	of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and
	a "Master In, Slave Out" (MISO) data line.
	SPI is a full duplex protocol; for each bit shifted out the
	MOSI line (one per clock) another is shifted in on the MISO line.
	Those bits are assembled into words of various sizes on the
	way to and from system memory.
	An additional chipselect line is usually active-low (nCS);
	four signals are normally used for each peripheral, plus
	sometimes an interrupt.
  </para>
  <para>
	The SPI bus facilities listed here provide a generalized
	interface to declare SPI busses and devices, manage them
	according to the standard Linux driver model, and perform
	input/output operations.
	At this time, only "master" side interfaces are supported,
	where Linux talks to SPI peripherals and does not implement
	such a peripheral itself.
	(Interfaces to support implementing SPI slaves would
	necessarily look different.)
  </para>
  <para>
	The programming interface is structured around two kinds of driver,
	and two kinds of device.
	A "Controller Driver" abstracts the controller hardware, which may
	be as simple as a set of GPIO pins or as complex as a pair of FIFOs
	connected to dual DMA engines on the other side of the SPI shift
	register (maximizing throughput).  Such drivers bridge between
	whatever bus they sit on (often the platform bus) and SPI, and
	expose the SPI side of their device as a
	<structname><link linkend="API-struct-spi-master">struct spi_master</link></structname>.
	SPI devices are children of that master, represented as a
	<structname><link linkend="API-struct-spi-device">struct spi_device</link></structname> and manufactured from
	<structname><link linkend="API-struct-spi-board-info">struct spi_board_info</link></structname> descriptors which
	are usually provided by board-specific initialization code.
	A <structname><link linkend="API-struct-spi-driver">struct spi_driver</link></structname> is called a
	"Protocol Driver", and is bound to a spi_device using normal
	driver model calls.
  </para>
  <para>
	The I/O model is a set of queued messages.  Protocol drivers
	submit one or more <structname><link linkend="API-struct-spi-message">struct spi_message</link></structname>
	objects, which are processed and completed asynchronously.
	(There are synchronous wrappers, however.)  Messages are
	built from one or more <structname><link linkend="API-struct-spi-transfer">struct spi_transfer</link></structname>
	objects, each of which wraps a full duplex SPI transfer.
	A variety of protocol tweaking options are needed, because
	different chips adopt very different policies for how they
	use the bits transferred with SPI.
  </para>
<!-- include/linux/spi/spi.h -->
<refentry id="API-struct-spi-statistics">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_statistics</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_statistics</refname>
 <refpurpose>
  statistics for spi transfers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_statistics {
  spinlock_t lock;
  unsigned long messages;
  unsigned long transfers;
  unsigned long errors;
  unsigned long timedout;
  unsigned long spi_sync;
  unsigned long spi_sync_immediate;
  unsigned long spi_async;
  unsigned long long bytes;
  unsigned long long bytes_rx;
  unsigned long long bytes_tx;
#define SPI_STATISTICS_HISTO_SIZE 17
  unsigned long transfer_bytes_histo[SPI_STATISTICS_HISTO_SIZE];
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>lock</term>
      <listitem><para>
lock protecting this structure
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>messages</term>
      <listitem><para>
number of spi-messages handled
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transfers</term>
      <listitem><para>
number of spi_transfers handled
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>errors</term>
      <listitem><para>
number of errors during spi_transfer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>timedout</term>
      <listitem><para>
number of timeouts during spi_transfer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>spi_sync</term>
      <listitem><para>
number of times spi_sync is used
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>spi_sync_immediate</term>
      <listitem><para>
number of times spi_sync is executed immediately
in calling context without queuing and scheduling
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>spi_async</term>
      <listitem><para>
number of times spi_async is used
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bytes</term>
      <listitem><para>
number of bytes transferred to/from device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bytes_rx</term>
      <listitem><para>
number of bytes received from device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bytes_tx</term>
      <listitem><para>
number of bytes sent to device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transfer_bytes_histo[SPI_STATISTICS_HISTO_SIZE]</term>
      <listitem><para>
transfer bytes histogramm
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-spi-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_device</refname>
 <refpurpose>
     Master side proxy for an SPI slave device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_device {
  struct device dev;
  struct spi_master * master;
  u32 max_speed_hz;
  u8 chip_select;
  u8 bits_per_word;
  u16 mode;
#define SPI_CPHA	0x01
#define SPI_CPOL	0x02
#define SPI_MODE_0	(0|0)
#define SPI_MODE_1	(0|SPI_CPHA)
#define SPI_MODE_2	(SPI_CPOL|0)
#define SPI_MODE_3	(SPI_CPOL|SPI_CPHA)
#define SPI_CS_HIGH	0x04
#define SPI_LSB_FIRST	0x08
#define SPI_3WIRE	0x10
#define SPI_LOOP	0x20
#define SPI_NO_CS	0x40
#define SPI_READY	0x80
#define SPI_TX_DUAL	0x100
#define SPI_TX_QUAD	0x200
#define SPI_RX_DUAL	0x400
#define SPI_RX_QUAD	0x800
  int irq;
  void * controller_state;
  void * controller_data;
  char modalias[SPI_NAME_SIZE];
  int cs_gpio;
  struct spi_statistics statistics;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   Driver model representation of the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>master</term>
      <listitem><para>
   SPI controller used with the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_speed_hz</term>
      <listitem><para>
   Maximum clock rate to be used with this chip
   (on this board); may be changed by the device's driver.
   The spi_transfer.speed_hz can override this for each transfer.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>chip_select</term>
      <listitem><para>
   Chipselect, distinguishing chips handled by <parameter>master</parameter>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bits_per_word</term>
      <listitem><para>
   Data transfers involve one or more words; word sizes
   like eight or 12 bits are common.  In-memory wordsizes are
   powers of two bytes (e.g. 20 bit samples use 32 bits).
   This may be changed by the device's driver, or left at the
   default (0) indicating protocol words are eight bit bytes.
   The spi_transfer.bits_per_word can override this for each transfer.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode</term>
      <listitem><para>
   The spi mode defines how data is clocked out and in.
   This may be changed by the device's driver.
   The <quote>active low</quote> default for chipselect mode can be overridden
   (by specifying SPI_CS_HIGH) as can the <quote>MSB first</quote> default for
   each word in a transfer (by specifying SPI_LSB_FIRST).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>irq</term>
      <listitem><para>
   Negative, or the number passed to <function>request_irq</function> to receive
   interrupts from this device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>controller_state</term>
      <listitem><para>
   Controller's runtime state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>controller_data</term>
      <listitem><para>
   Board-specific definitions for controller, such as
   FIFO initialization parameters; from board_info.controller_data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>modalias[SPI_NAME_SIZE]</term>
      <listitem><para>
   Name of the driver to use with this device, or an alias
   for that name.  This appears in the sysfs <quote>modalias</quote> attribute
   for driver coldplugging, and in uevents used for hotplugging
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cs_gpio</term>
      <listitem><para>
   gpio number of the chipselect line (optional, -ENOENT when
   when not using a GPIO line)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>statistics</term>
      <listitem><para>
   statistics for the spi_device
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   A <parameter>spi_device</parameter> is used to interchange data between an SPI slave
   (usually a discrete chip) and CPU memory.
   </para><para>

   In <parameter>dev</parameter>, the platform_data is used to hold information about this
   device that's meaningful to the device's protocol driver, but not
   to its controller.  One example might be an identifier for a chip
   variant with slightly different functionality; another might be
   information about how this particular board wires the chip's pins.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-spi-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_driver</refname>
 <refpurpose>
     Host side <quote>protocol</quote> driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_driver {
  const struct spi_device_id * id_table;
  int (* probe) (struct spi_device *spi);
  int (* remove) (struct spi_device *spi);
  void (* shutdown) (struct spi_device *spi);
  struct device_driver driver;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>id_table</term>
      <listitem><para>
   List of SPI devices supported by this driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>probe</term>
      <listitem><para>
   Binds this driver to the spi device.  Drivers can verify
   that the device is actually present, and may need to configure
   characteristics (such as bits_per_word) which weren't needed for
   the initial configuration done during system setup.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>remove</term>
      <listitem><para>
   Unbinds this driver from the spi device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>shutdown</term>
      <listitem><para>
   Standard shutdown callback used during system state
   transitions such as powerdown/halt and kexec
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver</term>
      <listitem><para>
   SPI device drivers should initialize the name and owner
   field of this structure.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This represents the kind of device driver that uses SPI messages to
   interact with the hardware at the other end of a SPI link.  It's called
   a <quote>protocol</quote> driver because it works through messages rather than talking
   directly to SPI hardware (which is what the underlying SPI controller
   driver does to pass those messages).  These protocols are defined in the
   specification for the device(s) supported by the driver.
   </para><para>

   As a rule, those device protocols represent the lowest level interface
   supported by a driver, and it will support upper level interfaces too.
   Examples of such upper levels include frameworks like MTD, networking,
   MMC, RTC, filesystem character device nodes, and hardware monitoring.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-unregister-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_unregister_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_unregister_driver</refname>
 <refpurpose>
     reverse effect of spi_register_driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>spi_unregister_driver </function></funcdef>
   <paramdef><link linkend="API-struct-spi-driver">struct spi_driver</link> * <parameter>sdrv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sdrv</parameter></term>
   <listitem>
    <para>
     the driver to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
</refentry>

<refentry id="API-module-spi-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>module_spi_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>module_spi_driver</refname>
 <refpurpose>
     Helper macro for registering a SPI driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>module_spi_driver </function></funcdef>
   <paramdef> <parameter>__spi_driver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>__spi_driver</parameter></term>
   <listitem>
    <para>
     spi_driver struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Helper macro for SPI drivers which do not do anything special in module
   init/exit. This eliminates a lot of boilerplate. Each module may only
   use this macro once, and calling it replaces <function>module_init</function> and <function>module_exit</function>
</para>
</refsect1>
</refentry>

<refentry id="API-struct-spi-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_master</refname>
 <refpurpose>
     interface to SPI master controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_master {
  struct device dev;
  struct list_head list;
  s16 bus_num;
  u16 num_chipselect;
  u16 dma_alignment;
  u16 mode_bits;
  u32 bits_per_word_mask;
#define SPI_BPW_MASK(bits) BIT((bits) - 1)
#define SPI_BIT_MASK(bits) (((bits) == 32) ? ~0U : (BIT(bits) - 1))
#define SPI_BPW_RANGE_MASK(min# max) (SPI_BIT_MASK(max) - SPI_BIT_MASK(min - 1))
  u32 min_speed_hz;
  u32 max_speed_hz;
  u16 flags;
#define SPI_MASTER_HALF_DUPLEX	BIT(0)
#define SPI_MASTER_NO_RX	BIT(1)
#define SPI_MASTER_NO_TX	BIT(2)
#define SPI_MASTER_MUST_RX      BIT(3)
#define SPI_MASTER_MUST_TX      BIT(4)
  spinlock_t bus_lock_spinlock;
  struct mutex bus_lock_mutex;
  bool bus_lock_flag;
  int (* setup) (struct spi_device *spi);
  int (* transfer) (struct spi_device *spi,struct spi_message *mesg);
  void (* cleanup) (struct spi_device *spi);
  bool (* can_dma) (struct spi_master *master,struct spi_device *spi,struct spi_transfer *xfer);
  bool queued;
  struct kthread_worker kworker;
  struct task_struct * kworker_task;
  struct kthread_work pump_messages;
  spinlock_t queue_lock;
  struct list_head queue;
  struct spi_message * cur_msg;
  bool idling;
  bool busy;
  bool running;
  bool rt;
  bool auto_runtime_pm;
  bool cur_msg_prepared;
  bool cur_msg_mapped;
  struct completion xfer_completion;
  size_t max_dma_len;
  int (* prepare_transfer_hardware) (struct spi_master *master);
  int (* transfer_one_message) (struct spi_master *master,struct spi_message *mesg);
  int (* unprepare_transfer_hardware) (struct spi_master *master);
  int (* prepare_message) (struct spi_master *master,struct spi_message *message);
  int (* unprepare_message) (struct spi_master *master,struct spi_message *message);
  void (* set_cs) (struct spi_device *spi, bool enable);
  int (* transfer_one) (struct spi_master *master, struct spi_device *spi,struct spi_transfer *transfer);
  void (* handle_err) (struct spi_master *master,struct spi_message *message);
  int * cs_gpios;
  struct spi_statistics statistics;
  struct dma_chan * dma_tx;
  struct dma_chan * dma_rx;
  void * dummy_rx;
  void * dummy_tx;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   device interface to this driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>list</term>
      <listitem><para>
   link with the global spi_master list
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus_num</term>
      <listitem><para>
   board-specific (and often SOC-specific) identifier for a
   given SPI controller.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_chipselect</term>
      <listitem><para>
   chipselects are used to distinguish individual
   SPI slaves, and are numbered from zero to num_chipselects.
   each slave has a chipselect signal, but it's common that not
   every chipselect is connected to a slave.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dma_alignment</term>
      <listitem><para>
   SPI controller constraint on DMA buffers alignment.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_bits</term>
      <listitem><para>
   flags understood by this controller driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bits_per_word_mask</term>
      <listitem><para>
   A mask indicating which values of bits_per_word are
   supported by the driver. Bit n indicates that a bits_per_word n+1 is
   supported. If set, the SPI core will reject any transfer with an
   unsupported bits_per_word. If not set, this value is simply ignored,
   and it's up to the individual driver to perform any validation.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>min_speed_hz</term>
      <listitem><para>
   Lowest supported transfer speed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_speed_hz</term>
      <listitem><para>
   Highest supported transfer speed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   other constraints relevant to this driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus_lock_spinlock</term>
      <listitem><para>
   spinlock for SPI bus locking
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus_lock_mutex</term>
      <listitem><para>
   mutex for SPI bus locking
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus_lock_flag</term>
      <listitem><para>
   indicates that the SPI bus is locked for exclusive use
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>setup</term>
      <listitem><para>
   updates the device mode and clocking records used by a
   device's SPI controller; protocol code may call this.  This
   must fail if an unrecognized or unsupported mode is requested.
   It's always safe to call this unless transfers are pending on
   the device whose settings are being modified.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transfer</term>
      <listitem><para>
   adds a message to the controller's transfer queue.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cleanup</term>
      <listitem><para>
   frees controller-specific state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>can_dma</term>
      <listitem><para>
   determine whether this master supports DMA
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>queued</term>
      <listitem><para>
   whether this master is providing an internal message queue
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>kworker</term>
      <listitem><para>
   thread struct for message pump
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>kworker_task</term>
      <listitem><para>
   pointer to task for message pump kworker thread
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pump_messages</term>
      <listitem><para>
   work struct for scheduling work to the message pump
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>queue_lock</term>
      <listitem><para>
   spinlock to syncronise access to message queue
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>queue</term>
      <listitem><para>
   message queue
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cur_msg</term>
      <listitem><para>
   the currently in-flight message
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>idling</term>
      <listitem><para>
   the device is entering idle state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>busy</term>
      <listitem><para>
   message pump is busy
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>running</term>
      <listitem><para>
   message pump is running
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rt</term>
      <listitem><para>
   whether this queue is set to run as a realtime task
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>auto_runtime_pm</term>
      <listitem><para>
   the core should ensure a runtime PM reference is held
   while the hardware is prepared, using the parent
   device for the spidev
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cur_msg_prepared</term>
      <listitem><para>
   spi_prepare_message was called for the currently
   in-flight message
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cur_msg_mapped</term>
      <listitem><para>
   message has been mapped for DMA
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>xfer_completion</term>
      <listitem><para>
   used by core <function>transfer_one_message</function>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_dma_len</term>
      <listitem><para>
   Maximum length of a DMA transfer for the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>prepare_transfer_hardware</term>
      <listitem><para>
   a message will soon arrive from the queue
   so the subsystem requests the driver to prepare the transfer hardware
   by issuing this call
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transfer_one_message</term>
      <listitem><para>
   the subsystem calls the driver to transfer a single
   message while queuing transfers that arrive in the meantime. When the
   driver is finished with this message, it must call
   <function><link linkend="API-spi-finalize-current-message">spi_finalize_current_message</link></function> so the subsystem can issue the next
   message
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>unprepare_transfer_hardware</term>
      <listitem><para>
   there are currently no more messages on the
   queue so the subsystem notifies the driver that it may relax the
   hardware by issuing this call
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>prepare_message</term>
      <listitem><para>
   set up the controller to transfer a single message,
   for example doing DMA mapping.  Called from threaded
   context.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>unprepare_message</term>
      <listitem><para>
   undo any work done by <function>prepare_message</function>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_cs</term>
      <listitem><para>
   set the logic level of the chip select line.  May be called
   from interrupt context.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transfer_one</term>
      <listitem><para>
   transfer a single spi_transfer.
   - return 0 if the transfer is finished,
   - return 1 if the transfer is still in progress. When
   the driver is finished with this transfer it must
   call <function><link linkend="API-spi-finalize-current-transfer">spi_finalize_current_transfer</link></function> so the subsystem
   can issue the next transfer. Note: transfer_one and
   transfer_one_message are mutually exclusive; when both
   are set, the generic subsystem does not call your
   transfer_one callback.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>handle_err</term>
      <listitem><para>
   the subsystem calls the driver to handle an error that occurs
   in the generic implementation of <function>transfer_one_message</function>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cs_gpios</term>
      <listitem><para>
   Array of GPIOs to use as chip select lines; one per CS
   number. Any individual value may be -ENOENT for CS lines that
   are not GPIOs (driven by the SPI controller itself).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>statistics</term>
      <listitem><para>
   statistics for the spi_master
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dma_tx</term>
      <listitem><para>
   DMA transmit channel
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dma_rx</term>
      <listitem><para>
   DMA receive channel
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dummy_rx</term>
      <listitem><para>
   dummy receive buffer for full-duplex devices
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dummy_tx</term>
      <listitem><para>
   dummy transmit buffer for full-duplex devices
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Each SPI master controller can communicate with one or more <parameter>spi_device</parameter>
   children.  These make a small bus, sharing MOSI, MISO and SCK signals
   but not chip select signals.  Each device may be configured to use a
   different clock rate, since those shared signals are ignored unless
   the chip is selected.
   </para><para>

   The driver for an SPI controller manages access to those devices through
   a queue of spi_message transactions, copying data between CPU memory and
   an SPI slave device.  For each such message it queues, it calls the
   message's completion function when the transaction completes.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-spi-transfer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_transfer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_transfer</refname>
 <refpurpose>
     a read/write buffer pair
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_transfer {
  const void * tx_buf;
  void * rx_buf;
  unsigned len;
  dma_addr_t tx_dma;
  dma_addr_t rx_dma;
  struct sg_table tx_sg;
  struct sg_table rx_sg;
  unsigned cs_change:1;
  unsigned tx_nbits:3;
  unsigned rx_nbits:3;
#define SPI_NBITS_SINGLE	0x01
#define SPI_NBITS_DUAL		0x02
#define SPI_NBITS_QUAD		0x04
  u8 bits_per_word;
  u16 delay_usecs;
  u32 speed_hz;
  struct list_head transfer_list;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>tx_buf</term>
      <listitem><para>
   data to be written (dma-safe memory), or NULL
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_buf</term>
      <listitem><para>
   data to be read (dma-safe memory), or NULL
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>len</term>
      <listitem><para>
   size of rx and tx buffers (in bytes)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_dma</term>
      <listitem><para>
   DMA address of tx_buf, if <parameter>spi_message</parameter>.is_dma_mapped
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_dma</term>
      <listitem><para>
   DMA address of rx_buf, if <parameter>spi_message</parameter>.is_dma_mapped
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_sg</term>
      <listitem><para>
   Scatterlist for transmit, currently not for client use
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_sg</term>
      <listitem><para>
   Scatterlist for receive, currently not for client use
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cs_change</term>
      <listitem><para>
   affects chipselect after this transfer completes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_nbits</term>
      <listitem><para>
   number of bits used for writing. If 0 the default
   (SPI_NBITS_SINGLE) is used.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_nbits</term>
      <listitem><para>
   number of bits used for reading. If 0 the default
   (SPI_NBITS_SINGLE) is used.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bits_per_word</term>
      <listitem><para>
   select a bits_per_word other than the device default
   for this transfer. If 0 the default (from <parameter>spi_device</parameter>) is used.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>delay_usecs</term>
      <listitem><para>
   microseconds to delay after this transfer before
   (optionally) changing the chipselect status, then starting
   the next transfer or completing this <parameter>spi_message</parameter>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>speed_hz</term>
      <listitem><para>
   Select a speed other than the device default for this
   transfer. If 0 the default (from <parameter>spi_device</parameter>) is used.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transfer_list</term>
      <listitem><para>
   transfers are sequenced through <parameter>spi_message</parameter>.transfers
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   SPI transfers always write the same number of bytes as they read.
   Protocol drivers should always provide <parameter>rx_buf</parameter> and/or <parameter>tx_buf</parameter>.
   In some cases, they may also want to provide DMA addresses for
   the data being transferred; that may reduce overhead, when the
   underlying driver uses dma.
   </para><para>

   If the transmit buffer is null, zeroes will be shifted out
   while filling <parameter>rx_buf</parameter>.  If the receive buffer is null, the data
   shifted in will be discarded.  Only <quote>len</quote> bytes shift out (or in).
   It's an error to try to shift out a partial word.  (For example, by
   shifting out three bytes with word size of sixteen or twenty bits;
   the former uses two bytes per word, the latter uses four bytes.)
   </para><para>

   In-memory data values are always in native CPU byte order, translated
   from the wire byte order (big-endian except with SPI_LSB_FIRST).  So
   for example when bits_per_word is sixteen, buffers are 2N bytes long
   (<parameter>len</parameter> = 2N) and hold N sixteen bit words in CPU byte order.
   </para><para>

   When the word size of the SPI transfer is not a power-of-two multiple
   of eight bits, those in-memory words include extra bits.  In-memory
   words are always seen by protocol drivers as right-justified, so the
   undefined (rx) or unused (tx) bits are always the most significant bits.
   </para><para>

   All SPI transfers start with the relevant chipselect active.  Normally
   it stays selected until after the last transfer in a message.  Drivers
   can affect the chipselect signal using cs_change.
   </para><para>

   (i) If the transfer isn't the last one in the message, this flag is
   used to make the chipselect briefly go inactive in the middle of the
   message.  Toggling chipselect in this way may be needed to terminate
   a chip command, letting a single spi_message perform all of group of
   chip transactions together.
   </para><para>

   (ii) When the transfer is the last one in the message, the chip may
   stay selected until the next transfer.  On multi-device SPI busses
   with nothing blocking messages going to other devices, this is just
   a performance hint; starting a message to another device deselects
   this one.  But in other cases, this can be used to ensure correctness.
   Some devices need protocol transactions to be built from a series of
   spi_message submissions, where the content of one message is determined
   by the results of previous messages and where the whole transaction
   ends when the chipselect goes intactive.
   </para><para>

   When SPI can transfer in 1x,2x or 4x. It can get this transfer information
   from device through <parameter>tx_nbits</parameter> and <parameter>rx_nbits</parameter>. In Bi-direction, these
   two should both be set. User can set transfer mode with SPI_NBITS_SINGLE(1x)
   SPI_NBITS_DUAL(2x) and SPI_NBITS_QUAD(4x) to support these three transfer.
   </para><para>

   The code that submits an spi_message (and its spi_transfers)
   to the lower layers is responsible for managing its memory.
   Zero-initialize every field you don't set up explicitly, to
   insulate against future API updates.  After you submit a message
   and its transfers, ignore them until its completion callback.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-spi-message">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_message</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_message</refname>
 <refpurpose>
     one multi-segment SPI transaction
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_message {
  struct list_head transfers;
  struct spi_device * spi;
  unsigned is_dma_mapped:1;
  void (* complete) (void *context);
  void * context;
  unsigned frame_length;
  unsigned actual_length;
  int status;
  struct list_head queue;
  void * state;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>transfers</term>
      <listitem><para>
   list of transfer segments in this transaction
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>spi</term>
      <listitem><para>
   SPI device to which the transaction is queued
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>is_dma_mapped</term>
      <listitem><para>
   if true, the caller provided both dma and cpu virtual
   addresses for each transfer buffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>complete</term>
      <listitem><para>
   called to report transaction completions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>context</term>
      <listitem><para>
   the argument to <function>complete</function> when it's called
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>frame_length</term>
      <listitem><para>
   the total number of bytes in the message
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>actual_length</term>
      <listitem><para>
   the total number of bytes that were transferred in all
   successful segments
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>status</term>
      <listitem><para>
   zero for success, else negative errno
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>queue</term>
      <listitem><para>
   for use by whichever driver currently owns the message
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>state</term>
      <listitem><para>
   for use by whichever driver currently owns the message
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   A <parameter>spi_message</parameter> is used to execute an atomic sequence of data transfers,
   each represented by a struct spi_transfer.  The sequence is <quote>atomic</quote>
   in the sense that no other spi_message may use that SPI bus until that
   sequence completes.  On some systems, many such sequences can execute as
   as single programmed DMA transfer.  On all systems, these messages are
   queued, and might complete after transactions to other devices.  Messages
   sent to a given spi_device are always executed in FIFO order.
   </para><para>

   The code that submits an spi_message (and its spi_transfers)
   to the lower layers is responsible for managing its memory.
   Zero-initialize every field you don't set up explicitly, to
   insulate against future API updates.  After you submit a message
   and its transfers, ignore them until its completion callback.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-message-init-with-transfers">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_message_init_with_transfers</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_message_init_with_transfers</refname>
 <refpurpose>
     Initialize spi_message and append transfers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>spi_message_init_with_transfers </function></funcdef>
   <paramdef><link linkend="API-struct-spi-message">struct spi_message</link> * <parameter>m</parameter></paramdef>
   <paramdef><link linkend="API-struct-spi-transfer">struct spi_transfer</link> * <parameter>xfers</parameter></paramdef>
   <paramdef>unsigned int <parameter>num_xfers</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     spi_message to be initialized
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>xfers</parameter></term>
   <listitem>
    <para>
     An array of spi transfers
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_xfers</parameter></term>
   <listitem>
    <para>
     Number of items in the xfer array
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function initializes the given spi_message and adds each spi_transfer in
   the given array to the message.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_write</refname>
 <refpurpose>
     SPI synchronous write
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_write </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
   <paramdef>const void * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device to which data will be written
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     data buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     data buffer size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function writes the buffer <parameter>buf</parameter>.
   Callable only from contexts that can sleep.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_read</refname>
 <refpurpose>
     SPI synchronous read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_read </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
   <paramdef>void * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device from which data will be read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     data buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     data buffer size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function reads the buffer <parameter>buf</parameter>.
   Callable only from contexts that can sleep.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-sync-transfer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_sync_transfer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_sync_transfer</refname>
 <refpurpose>
     synchronous SPI data transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_sync_transfer </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
   <paramdef><link linkend="API-struct-spi-transfer">struct spi_transfer</link> * <parameter>xfers</parameter></paramdef>
   <paramdef>unsigned int <parameter>num_xfers</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>xfers</parameter></term>
   <listitem>
    <para>
     An array of spi_transfers
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_xfers</parameter></term>
   <listitem>
    <para>
     Number of items in the xfer array
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Does a synchronous SPI data transfer of the given spi_transfer array.
   </para><para>

   For more specific semantics see <function><link linkend="API-spi-sync">spi_sync</link></function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Return: zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-w8r8">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_w8r8</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_w8r8</refname>
 <refpurpose>
     SPI synchronous 8 bit write followed by 8 bit read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>spi_w8r8 </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
   <paramdef>u8 <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     command to be written before data is read back
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Callable only from contexts that can sleep.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   the (unsigned) eight bit number returned by the
   device, or else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-w8r16">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_w8r16</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_w8r16</refname>
 <refpurpose>
     SPI synchronous 8 bit write followed by 16 bit read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>spi_w8r16 </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
   <paramdef>u8 <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     command to be written before data is read back
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The number is returned in wire-order, which is at least sometimes
   big-endian.
   </para><para>

   Callable only from contexts that can sleep.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   the (unsigned) sixteen bit number returned by the
   device, or else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-w8r16be">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_w8r16be</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_w8r16be</refname>
 <refpurpose>
     SPI synchronous 8 bit write followed by 16 bit big-endian read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>spi_w8r16be </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
   <paramdef>u8 <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     command to be written before data is read back
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is similar to spi_w8r16, with the exception that it will
   convert the read 16 bit data word from big-endian to native endianness.
   </para><para>

   Callable only from contexts that can sleep.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   the (unsigned) sixteen bit number returned by the device in cpu
   endianness, or else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-spi-board-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_board_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_board_info</refname>
 <refpurpose>
     board-specific template for a SPI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_board_info {
  char modalias[SPI_NAME_SIZE];
  const void * platform_data;
  void * controller_data;
  int irq;
  u32 max_speed_hz;
  u16 bus_num;
  u16 chip_select;
  u16 mode;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>modalias[SPI_NAME_SIZE]</term>
      <listitem><para>
   Initializes spi_device.modalias; identifies the driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>platform_data</term>
      <listitem><para>
   Initializes spi_device.platform_data; the particular
   data stored there is driver-specific.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>controller_data</term>
      <listitem><para>
   Initializes spi_device.controller_data; some
   controllers need hints about hardware setup, e.g. for DMA.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>irq</term>
      <listitem><para>
   Initializes spi_device.irq; depends on how the board is wired.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_speed_hz</term>
      <listitem><para>
   Initializes spi_device.max_speed_hz; based on limits
   from the chip datasheet and board-specific signal quality issues.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus_num</term>
      <listitem><para>
   Identifies which spi_master parents the spi_device; unused
   by <function><link linkend="API-spi-new-device">spi_new_device</link></function>, and otherwise depends on board wiring.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>chip_select</term>
      <listitem><para>
   Initializes spi_device.chip_select; depends on how
   the board is wired.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode</term>
      <listitem><para>
   Initializes spi_device.mode; based on the chip datasheet, board
   wiring (some devices support both 3WIRE and standard modes), and
   possibly presence of an inverter in the chipselect path.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   When adding new SPI devices to the device tree, these structures serve
   as a partial device template.  They hold information which can't always
   be determined by drivers.  Information that <function>probe</function> can establish (such
   as the default transfer wordsize) is not included here.
   </para><para>

   These structures are used in two places.  Their primary role is to
   be stored in tables of board-specific device descriptors, which are
   declared early in board initialization and then used (much later) to
   populate a controller's device tree after the that controller's driver
   initializes.  A secondary (and atypical) role is as a parameter to
   <function><link linkend="API-spi-new-device">spi_new_device</link></function> call, which happens after those controller drivers
   are active in some dynamic board configuration models.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-register-board-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_register_board_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_register_board_info</refname>
 <refpurpose>
  register SPI devices for a given board
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_register_board_info </function></funcdef>
   <paramdef>struct spi_board_info const * <parameter>info</parameter></paramdef>
   <paramdef>unsigned <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     array of chip descriptors
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     how many descriptors are provided
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Board-specific early init code calls this (probably during arch_initcall)
   with segments of the SPI device table.  Any device nodes are created later,
   after the relevant parent SPI controller (bus_num) is defined.  We keep
   this table of devices forever, so that reloading a controller driver will
   not make Linux forget about these hard-wired devices.
   </para><para>

   Other code can also call this, e.g. a particular add-on board might provide
   SPI devices through its expansion connector, so code initializing that board
   would naturally declare its SPI devices.
   </para><para>

   The board info passed can safely be __initdata ... but be careful of
   any embedded pointers (platform_data, etc), they're copied as-is.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<!-- drivers/spi/spi.c -->
<refentry id="API---spi-register-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__spi_register_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__spi_register_driver</refname>
 <refpurpose>
  register a SPI driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__spi_register_driver </function></funcdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
   <paramdef><link linkend="API-struct-spi-driver">struct spi_driver</link> * <parameter>sdrv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     owner module of the driver to register
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sdrv</parameter></term>
   <listitem>
    <para>
     the driver to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-alloc-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_alloc_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_alloc_device</refname>
 <refpurpose>
     Allocate a new SPI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-spi-device">struct spi_device</link> * <function>spi_alloc_device </function></funcdef>
   <paramdef><link linkend="API-struct-spi-master">struct spi_master</link> * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     Controller to which device is connected
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allows a driver to allocate and initialize a spi_device without
   registering it immediately.  This allows a driver to directly
   fill the spi_device with device parameters before calling
   <function><link linkend="API-spi-add-device">spi_add_device</link></function> on it.
   </para><para>

   Caller is responsible to call <function><link linkend="API-spi-add-device">spi_add_device</link></function> on the returned
   spi_device structure to add it to the SPI master.  If the caller
   needs to discard the spi_device without adding it, then it should
   call <function>spi_dev_put</function> on it.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   a pointer to the new device, or NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-add-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_add_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_add_device</refname>
 <refpurpose>
     Add spi_device allocated with spi_alloc_device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_add_device </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     spi_device to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Companion function to spi_alloc_device.  Devices allocated with
   spi_alloc_device can be added onto the spi bus with this function.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success; negative errno on failure
</para>
</refsect1>
</refentry>

<refentry id="API-spi-new-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_new_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_new_device</refname>
 <refpurpose>
     instantiate one new SPI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-spi-device">struct spi_device</link> * <function>spi_new_device </function></funcdef>
   <paramdef><link linkend="API-struct-spi-master">struct spi_master</link> * <parameter>master</parameter></paramdef>
   <paramdef><link linkend="API-struct-spi-board-info">struct spi_board_info</link> * <parameter>chip</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     Controller to which device is connected
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>chip</parameter></term>
   <listitem>
    <para>
     Describes the SPI device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   On typical mainboards, this is purely internal; and it's not needed
   after board init creates the hard-wired devices.  Some development
   platforms may not be able to use spi_register_board_info though, and
   this is exported so that for example a USB or parport based adapter
   driver could add devices (which it would learn about out-of-band).
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   the new device, or NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-finalize-current-transfer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_finalize_current_transfer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_finalize_current_transfer</refname>
 <refpurpose>
     report completion of a transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>spi_finalize_current_transfer </function></funcdef>
   <paramdef><link linkend="API-struct-spi-master">struct spi_master</link> * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     the master reporting completion
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called by SPI drivers using the core <function>transfer_one_message</function>
   implementation to notify it that the current interrupt driven
   transfer has finished and the next one may be scheduled.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-get-next-queued-message">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_get_next_queued_message</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_get_next_queued_message</refname>
 <refpurpose>
     called by driver to check for queued messages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-spi-message">struct spi_message</link> * <function>spi_get_next_queued_message </function></funcdef>
   <paramdef><link linkend="API-struct-spi-master">struct spi_master</link> * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     the master to check for queued messages
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If there are more messages in the queue, the next message is returned from
   this call.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   the next message in the queue, else NULL if the queue is empty.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-finalize-current-message">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_finalize_current_message</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_finalize_current_message</refname>
 <refpurpose>
     the current message is complete
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>spi_finalize_current_message </function></funcdef>
   <paramdef><link linkend="API-struct-spi-master">struct spi_master</link> * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     the master to return the message to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called by the driver to notify the core that the message in the front of the
   queue is complete and can be removed from the queue.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-alloc-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_alloc_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_alloc_master</refname>
 <refpurpose>
     allocate SPI master controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-spi-master">struct spi_master</link> * <function>spi_alloc_master </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the controller, possibly using the platform_bus
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     how much zeroed driver-private data to allocate; the pointer to this
     memory is in the driver_data field of the returned device,
     accessible with <function>spi_master_get_devdata</function>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call is used only by SPI master controller drivers, which are the
   only ones directly touching chip registers.  It's how they allocate
   an spi_master structure, prior to calling <function><link linkend="API-spi-register-master">spi_register_master</link></function>.
   </para><para>

   This must be called from context that can sleep.
   </para><para>

   The caller is responsible for assigning the bus number and initializing
   the master's methods before calling <function><link linkend="API-spi-register-master">spi_register_master</link></function>; and (after errors
   adding the device) calling <function>spi_master_put</function> to prevent a memory leak.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   the SPI master structure on success, else NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-register-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_register_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_register_master</refname>
 <refpurpose>
     register SPI master controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_register_master </function></funcdef>
   <paramdef><link linkend="API-struct-spi-master">struct spi_master</link> * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     initialized master, originally from <function><link linkend="API-spi-alloc-master">spi_alloc_master</link></function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   SPI master controllers connect to their drivers using some non-SPI bus,
   such as the platform bus.  The final stage of <function>probe</function> in that code
   includes calling <function><link linkend="API-spi-register-master">spi_register_master</link></function> to hook up to this SPI bus glue.
   </para><para>

   SPI controllers use board specific (often SOC specific) bus numbers,
   and board-specific addressing for SPI devices combines those numbers
   with chip select numbers.  Since SPI does not directly support dynamic
   device identification, boards need configuration tables telling which
   chip is at which address.
   </para><para>

   This must be called from context that can sleep.  It returns zero on
   success, else a negative error code (dropping the master's refcount).
   After a successful return, the caller is responsible for calling
   <function><link linkend="API-spi-unregister-master">spi_unregister_master</link></function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-spi-register-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_spi_register_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_spi_register_master</refname>
 <refpurpose>
     register managed SPI master controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>devm_spi_register_master </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef><link linkend="API-struct-spi-master">struct spi_master</link> * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device managing SPI master
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     initialized master, originally from <function><link linkend="API-spi-alloc-master">spi_alloc_master</link></function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register a SPI device as with <function><link linkend="API-spi-register-master">spi_register_master</link></function> which will
   automatically be unregister
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-unregister-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_unregister_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_unregister_master</refname>
 <refpurpose>
     unregister SPI master controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>spi_unregister_master </function></funcdef>
   <paramdef><link linkend="API-struct-spi-master">struct spi_master</link> * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     the master being unregistered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call is used only by SPI master controller drivers, which are the
   only ones directly touching chip registers.
   </para><para>

   This must be called from context that can sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-busnum-to-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_busnum_to_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_busnum_to_master</refname>
 <refpurpose>
     look up master associated with bus_num
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-spi-master">struct spi_master</link> * <function>spi_busnum_to_master </function></funcdef>
   <paramdef>u16 <parameter>bus_num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus_num</parameter></term>
   <listitem>
    <para>
     the master's bus number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call may be used with devices that are registered after
   arch init time.  It returns a refcounted pointer to the relevant
   spi_master (which the caller must release), or NULL if there is
   no such master registered.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   the SPI master structure on success, else NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-setup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_setup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_setup</refname>
 <refpurpose>
     setup SPI mode and clock rate
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_setup </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     the device whose settings are being modified
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep, and no requests are queued to the device
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   SPI protocol drivers may need to update the transfer mode if the
   device doesn't work with its default.  They may likewise need
   to update clock rates or word sizes from initial values.  This function
   changes those settings, and must be called from a context that can sleep.
   Except for SPI_CS_HIGH, which takes effect immediately, the changes take
   effect the next time the device is selected and data is transferred to
   or from it.  When this function returns, the spi device is deselected.
   </para><para>

   Note that this call will fail if the protocol driver specifies an option
   that the underlying controller or its driver does not support.  For
   example, not all hardware supports wire transfers using nine bit words,
   LSB-first wire encoding, or active-high chipselects.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-async">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_async</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_async</refname>
 <refpurpose>
     asynchronous SPI transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_async </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
   <paramdef><link linkend="API-struct-spi-message">struct spi_message</link> * <parameter>message</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>message</parameter></term>
   <listitem>
    <para>
     describes the data transfers, including completion callback
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   any (irqs may be blocked, etc)
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call may be used in_irq and other contexts which can't sleep,
   as well as from task contexts which can sleep.
   </para><para>

   The completion callback is invoked in a context which can't sleep.
   Before that invocation, the value of message-&gt;status is undefined.
   When the callback is issued, message-&gt;status holds either zero (to
   indicate complete success) or a negative error code.  After that
   callback returns, the driver which issued the transfer request may
   deallocate the associated memory; it's no longer in use by any SPI
   core or controller driver code.
   </para><para>

   Note that although all messages to a spi_device are handled in
   FIFO order, messages may go to different devices in other orders.
   Some device might be higher priority, or have various <quote>hard</quote> access
   time requirements, for example.
   </para><para>

   On detection of any fault during the transfer, processing of
   the entire message is aborted, and the device is deselected.
   Until returning from the associated message completion callback,
   no other spi_message queued to that device will be processed.
   (This rule applies equally to all the synchronous transfer calls,
   which are wrappers around this core asynchronous primitive.)
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-async-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_async_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_async_locked</refname>
 <refpurpose>
     version of spi_async with exclusive bus usage
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_async_locked </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
   <paramdef><link linkend="API-struct-spi-message">struct spi_message</link> * <parameter>message</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>message</parameter></term>
   <listitem>
    <para>
     describes the data transfers, including completion callback
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   any (irqs may be blocked, etc)
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call may be used in_irq and other contexts which can't sleep,
   as well as from task contexts which can sleep.
   </para><para>

   The completion callback is invoked in a context which can't sleep.
   Before that invocation, the value of message-&gt;status is undefined.
   When the callback is issued, message-&gt;status holds either zero (to
   indicate complete success) or a negative error code.  After that
   callback returns, the driver which issued the transfer request may
   deallocate the associated memory; it's no longer in use by any SPI
   core or controller driver code.
   </para><para>

   Note that although all messages to a spi_device are handled in
   FIFO order, messages may go to different devices in other orders.
   Some device might be higher priority, or have various <quote>hard</quote> access
   time requirements, for example.
   </para><para>

   On detection of any fault during the transfer, processing of
   the entire message is aborted, and the device is deselected.
   Until returning from the associated message completion callback,
   no other spi_message queued to that device will be processed.
   (This rule applies equally to all the synchronous transfer calls,
   which are wrappers around this core asynchronous primitive.)
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-sync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_sync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_sync</refname>
 <refpurpose>
     blocking/synchronous SPI data transfers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_sync </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
   <paramdef><link linkend="API-struct-spi-message">struct spi_message</link> * <parameter>message</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>message</parameter></term>
   <listitem>
    <para>
     describes the data transfers
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call may only be used from a context that may sleep.  The sleep
   is non-interruptible, and has no timeout.  Low-overhead controller
   drivers may DMA directly into and out of the message buffers.
   </para><para>

   Note that the SPI device's chip select is active during the message,
   and then is normally disabled between messages.  Drivers for some
   frequently-used devices may want to minimize costs of selecting a chip,
   by leaving it selected in anticipation that the next message will go
   to the same chip.  (That may increase power usage.)
   </para><para>

   Also, the caller is guaranteeing that the memory associated with the
   message will not be freed before this call returns.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-sync-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_sync_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_sync_locked</refname>
 <refpurpose>
     version of spi_sync with exclusive bus usage
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_sync_locked </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
   <paramdef><link linkend="API-struct-spi-message">struct spi_message</link> * <parameter>message</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>message</parameter></term>
   <listitem>
    <para>
     describes the data transfers
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call may only be used from a context that may sleep.  The sleep
   is non-interruptible, and has no timeout.  Low-overhead controller
   drivers may DMA directly into and out of the message buffers.
   </para><para>

   This call should be used by drivers that require exclusive access to the
   SPI bus. It has to be preceded by a spi_bus_lock call. The SPI bus must
   be released by a spi_bus_unlock call when the exclusive access is over.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-bus-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_bus_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_bus_lock</refname>
 <refpurpose>
     obtain a lock for exclusive SPI bus usage
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_bus_lock </function></funcdef>
   <paramdef><link linkend="API-struct-spi-master">struct spi_master</link> * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     SPI bus master that should be locked for exclusive bus access
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call may only be used from a context that may sleep.  The sleep
   is non-interruptible, and has no timeout.
   </para><para>

   This call should be used by drivers that require exclusive access to the
   SPI bus. The SPI bus must be released by a spi_bus_unlock call when the
   exclusive access is over. Data transfer must be done by spi_sync_locked
   and spi_async_locked calls when the SPI bus lock is held.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   always zero.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-bus-unlock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_bus_unlock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_bus_unlock</refname>
 <refpurpose>
     release the lock for exclusive SPI bus usage
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_bus_unlock </function></funcdef>
   <paramdef><link linkend="API-struct-spi-master">struct spi_master</link> * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     SPI bus master that was locked for exclusive bus access
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call may only be used from a context that may sleep.  The sleep
   is non-interruptible, and has no timeout.
   </para><para>

   This call releases an SPI bus lock previously obtained by an spi_bus_lock
   call.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   always zero.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-write-then-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_write_then_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_write_then_read</refname>
 <refpurpose>
     SPI synchronous write followed by read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_write_then_read </function></funcdef>
   <paramdef><link linkend="API-struct-spi-device">struct spi_device</link> * <parameter>spi</parameter></paramdef>
   <paramdef>const void * <parameter>txbuf</parameter></paramdef>
   <paramdef>unsigned <parameter>n_tx</parameter></paramdef>
   <paramdef>void * <parameter>rxbuf</parameter></paramdef>
   <paramdef>unsigned <parameter>n_rx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>txbuf</parameter></term>
   <listitem>
    <para>
     data to be written (need not be dma-safe)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n_tx</parameter></term>
   <listitem>
    <para>
     size of txbuf, in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rxbuf</parameter></term>
   <listitem>
    <para>
     buffer into which data will be read (need not be dma-safe)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n_rx</parameter></term>
   <listitem>
    <para>
     size of rxbuf, in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This performs a half duplex MicroWire style transaction with the
   device, sending txbuf and then reading rxbuf.  The return value
   is zero for success, else a negative errno status code.
   This call may only be used from a context that may sleep.
   </para><para>

   Parameters to this routine are always copied using a small buffer;
   portable code should never use this for more than 32 bytes.
   Performance-sensitive or bulk transfer code should instead use
   spi_{async,sync}() calls with dma-safe buffers.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   zero on success, else a negative error code.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="i2c">
     <title>I<superscript>2</superscript>C and SMBus Subsystem</title>

     <para>
	I<superscript>2</superscript>C (or without fancy typography, "I2C")
	is an acronym for the "Inter-IC" bus, a simple bus protocol which is
	widely used where low data rate communications suffice.
	Since it's also a licensed trademark, some vendors use another
	name (such as "Two-Wire Interface", TWI) for the same bus.
	I2C only needs two signals (SCL for clock, SDA for data), conserving
	board real estate and minimizing signal quality issues.
	Most I2C devices use seven bit addresses, and bus speeds of up
	to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet
	found wide use.
	I2C is a multi-master bus; open drain signaling is used to
	arbitrate between masters, as well as to handshake and to
	synchronize clocks from slower clients.
     </para>

     <para>
	The Linux I2C programming interfaces support only the master
	side of bus interactions, not the slave side.
	The programming interface is structured around two kinds of driver,
	and two kinds of device.
	An I2C "Adapter Driver" abstracts the controller hardware; it binds
	to a physical device (perhaps a PCI device or platform_device) and
	exposes a <structname>struct i2c_adapter</structname> representing
	each I2C bus segment it manages.
	On each I2C bus segment will be I2C devices represented by a
	<structname><link linkend="API-struct-i2c-client">struct i2c_client</link></structname>.  Those devices will
	be bound to a <structname><link linkend="API-struct-i2c-driver">struct i2c_driver</link></structname>,
	which should follow the standard Linux driver model.
	(At this writing, a legacy model is more widely used.)
	There are functions to perform various I2C protocol operations; at
	this writing all such functions are usable only from task context.
     </para>

     <para>
	The System Management Bus (SMBus) is a sibling protocol.  Most SMBus
	systems are also I2C conformant.  The electrical constraints are
	tighter for SMBus, and it standardizes particular protocol messages
	and idioms.  Controllers that support I2C can also support most
	SMBus operations, but SMBus controllers don't support all the protocol
	options that an I2C controller will.
	There are functions to perform various SMBus protocol operations,
	either using I2C primitives or by issuing SMBus commands to
	i2c_adapter devices which don't support those I2C operations.
     </para>

<!-- include/linux/i2c.h -->
<refentry id="API-struct-i2c-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct i2c_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct i2c_driver</refname>
 <refpurpose>
  represent an I2C device driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct i2c_driver {
  unsigned int class;
  int (* attach_adapter) (struct i2c_adapter *);
  int (* probe) (struct i2c_client *, const struct i2c_device_id *);
  int (* remove) (struct i2c_client *);
  void (* shutdown) (struct i2c_client *);
  void (* alert) (struct i2c_client *, unsigned int data);
  int (* command) (struct i2c_client *client, unsigned int cmd, void *arg);
  struct device_driver driver;
  const struct i2c_device_id * id_table;
  int (* detect) (struct i2c_client *, struct i2c_board_info *);
  const unsigned short * address_list;
  struct list_head clients;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>class</term>
      <listitem><para>
What kind of i2c device we instantiate (for detect)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>attach_adapter</term>
      <listitem><para>
Callback for bus addition (deprecated)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>probe</term>
      <listitem><para>
Callback for device binding
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>remove</term>
      <listitem><para>
Callback for device unbinding
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>shutdown</term>
      <listitem><para>
Callback for device shutdown
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>alert</term>
      <listitem><para>
Alert callback, for example for the SMBus alert protocol
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>command</term>
      <listitem><para>
Callback for bus-wide signaling (optional)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver</term>
      <listitem><para>
Device driver model driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id_table</term>
      <listitem><para>
List of I2C devices supported by this driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>detect</term>
      <listitem><para>
Callback for device detection
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>address_list</term>
      <listitem><para>
The I2C addresses to probe (for detect)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>clients</term>
      <listitem><para>
List of detected clients we created (for i2c-core use only)
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   The driver.owner field should be set to the module owner of this driver.
   The driver.name field should be set to the name of this driver.
   </para><para>

   For automatic device detection, both <parameter>detect</parameter> and <parameter>address_list</parameter> must
   be defined. <parameter>class</parameter> should also be set, otherwise only devices forced
   with module parameters will be created. The detect function must
   fill at least the name field of the i2c_board_info structure it is
   handed upon successful detection, and possibly also the flags field.
   </para><para>

   If <parameter>detect</parameter> is missing, the driver will still work fine for enumerated
   devices. Detected devices simply won't be supported. This is expected
   for the many I2C/SMBus devices which can't be detected reliably, and
   the ones which can always be enumerated in practice.
   </para><para>

   The i2c_client structure which is handed to the <parameter>detect</parameter> callback is
   not a real i2c_client. It is initialized just enough so that you can
   call i2c_smbus_read_byte_data and friends on it. Don't do anything
   else with it. In particular, calling dev_dbg and friends on it is
   not allowed.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-i2c-client">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct i2c_client</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct i2c_client</refname>
 <refpurpose>
     represent an I2C slave device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct i2c_client {
  unsigned short flags;
  unsigned short addr;
  char name[I2C_NAME_SIZE];
  struct i2c_adapter * adapter;
  struct device dev;
  int irq;
  struct list_head detected;
#if IS_ENABLED(CONFIG_I2C_SLAVE)
  i2c_slave_cb_t slave_cb;
#endif
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   I2C_CLIENT_TEN indicates the device uses a ten bit chip address;
   I2C_CLIENT_PEC indicates it uses SMBus Packet Error Checking
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>addr</term>
      <listitem><para>
   Address used on the I2C bus connected to the parent adapter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name[I2C_NAME_SIZE]</term>
      <listitem><para>
   Indicates the type of the device, usually a chip name that's
   generic enough to hide second-sourcing and compatible revisions.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>adapter</term>
      <listitem><para>
   manages the bus segment hosting this I2C device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   Driver model device node for the slave.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>irq</term>
      <listitem><para>
   indicates the IRQ generated by this device (if any)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>detected</term>
      <listitem><para>
   member of an i2c_driver.clients list or i2c-core's
   userspace_devices list
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>slave_cb</term>
      <listitem><para>
   Callback when I2C slave mode of an adapter is used. The adapter
   calls it to pass on slave events to the slave driver.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   An i2c_client identifies a single device (i.e. chip) connected to an
   i2c bus. The behaviour exposed to Linux is defined by the driver
   managing the device.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-i2c-board-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct i2c_board_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct i2c_board_info</refname>
 <refpurpose>
     template for device creation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct i2c_board_info {
  char type[I2C_NAME_SIZE];
  unsigned short flags;
  unsigned short addr;
  void * platform_data;
  struct dev_archdata * archdata;
  struct device_node * of_node;
  struct fwnode_handle * fwnode;
  int irq;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>type[I2C_NAME_SIZE]</term>
      <listitem><para>
   chip type, to initialize i2c_client.name
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   to initialize i2c_client.flags
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>addr</term>
      <listitem><para>
   stored in i2c_client.addr
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>platform_data</term>
      <listitem><para>
   stored in i2c_client.dev.platform_data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>archdata</term>
      <listitem><para>
   copied into i2c_client.dev.archdata
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>of_node</term>
      <listitem><para>
   pointer to OpenFirmware device node
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fwnode</term>
      <listitem><para>
   device node supplied by the platform firmware
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>irq</term>
      <listitem><para>
   stored in i2c_client.irq
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   I2C doesn't actually support hardware probing, although controllers and
   devices may be able to use I2C_SMBUS_QUICK to tell whether or not there's
   a device at a given address.  Drivers commonly need more information than
   that, such as chip type, configuration, associated IRQ, and so on.
   </para><para>

   i2c_board_info is used to build tables of information listing I2C devices
   that are present.  This information is used to grow the driver model tree.
   For mainboards this is done statically using <function><link linkend="API-i2c-register-board-info">i2c_register_board_info</link></function>;
   bus numbers identify adapters that aren't yet available.  For add-on boards,
   <function><link linkend="API-i2c-new-device">i2c_new_device</link></function> does this dynamically with the adapter already known.
</para>
</refsect1>
</refentry>

<refentry id="API-I2C-BOARD-INFO">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>I2C_BOARD_INFO</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>I2C_BOARD_INFO</refname>
 <refpurpose>
     macro used to list an i2c device and its address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>I2C_BOARD_INFO </function></funcdef>
   <paramdef> <parameter>dev_type</parameter></paramdef>
   <paramdef> <parameter>dev_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_type</parameter></term>
   <listitem>
    <para>
     identifies the device type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev_addr</parameter></term>
   <listitem>
    <para>
     the device's address on the bus.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro initializes essential fields of a struct i2c_board_info,
   declaring what has been provided on a particular board.  Optional
   fields (such as associated irq, or device-specific platform_data)
   are provided using conventional syntax.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-i2c-algorithm">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct i2c_algorithm</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct i2c_algorithm</refname>
 <refpurpose>
     represent I2C transfer method
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct i2c_algorithm {
  int (* master_xfer) (struct i2c_adapter *adap, struct i2c_msg *msgs,int num);
  int (* smbus_xfer) (struct i2c_adapter *adap, u16 addr,unsigned short flags, char read_write,u8 command, int size, union i2c_smbus_data *data);
  u32 (* functionality) (struct i2c_adapter *);
#if IS_ENABLED(CONFIG_I2C_SLAVE)
  int (* reg_slave) (struct i2c_client *client);
  int (* unreg_slave) (struct i2c_client *client);
#endif
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>master_xfer</term>
      <listitem><para>
   Issue a set of i2c transactions to the given I2C adapter
   defined by the msgs array, with num messages available to transfer via
   the adapter specified by adap.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>smbus_xfer</term>
      <listitem><para>
   Issue smbus transactions to the given I2C adapter. If this
   is not present, then the bus layer will try and convert the SMBus calls
   into I2C transfers instead.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>functionality</term>
      <listitem><para>
   Return the flags that this algorithm/adapter pair supports
   from the I2C_FUNC_* flags.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>reg_slave</term>
      <listitem><para>
   Register given client to I2C slave mode of this adapter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>unreg_slave</term>
      <listitem><para>
   Unregister given client from I2C slave mode of this adapter
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>The following structs are for those who like to implement new bus drivers</title>
<para>
   i2c_algorithm is the interface to a class of hardware solutions which can
   be addressed using the same bus algorithms - i.e. bit-banging or the PCF8584
   to name two of the most common.
   </para><para>

   The return codes from the <parameter>master_xfer</parameter> field should indicate the type of
   error code that occurred during the transfer, as documented in the kernel
   Documentation file Documentation/i2c/fault-codes.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-i2c-bus-recovery-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct i2c_bus_recovery_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct i2c_bus_recovery_info</refname>
 <refpurpose>
     I2C bus recovery information
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct i2c_bus_recovery_info {
  int (* recover_bus) (struct i2c_adapter *);
  int (* get_scl) (struct i2c_adapter *);
  void (* set_scl) (struct i2c_adapter *, int val);
  int (* get_sda) (struct i2c_adapter *);
  void (* prepare_recovery) (struct i2c_adapter *);
  void (* unprepare_recovery) (struct i2c_adapter *);
  int scl_gpio;
  int sda_gpio;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>recover_bus</term>
      <listitem><para>
   Recover routine. Either pass driver's <function>recover_bus</function> routine, or
   <function>i2c_generic_scl_recovery</function> or <function>i2c_generic_gpio_recovery</function>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_scl</term>
      <listitem><para>
   This gets current value of SCL line. Mandatory for generic SCL
   recovery. Used internally for generic GPIO recovery.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_scl</term>
      <listitem><para>
   This sets/clears SCL line. Mandatory for generic SCL recovery. Used
   internally for generic GPIO recovery.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_sda</term>
      <listitem><para>
   This gets current value of SDA line. Optional for generic SCL
   recovery. Used internally, if sda_gpio is a valid GPIO, for generic GPIO
   recovery.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>prepare_recovery</term>
      <listitem><para>
   This will be called before starting recovery. Platform may
   configure padmux here for SDA/SCL line or something else they want.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>unprepare_recovery</term>
      <listitem><para>
   This will be called after completing recovery. Platform
   may configure padmux here for SDA/SCL line or something else they want.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>scl_gpio</term>
      <listitem><para>
   gpio number of the SCL line. Only required for GPIO recovery.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sda_gpio</term>
      <listitem><para>
   gpio number of the SDA line. Only required for GPIO recovery.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-i2c-adapter-quirks">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct i2c_adapter_quirks</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct i2c_adapter_quirks</refname>
 <refpurpose>
     describe flaws of an i2c adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct i2c_adapter_quirks {
  u64 flags;
  int max_num_msgs;
  u16 max_write_len;
  u16 max_read_len;
  u16 max_comb_1st_msg_len;
  u16 max_comb_2nd_msg_len;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   see I2C_AQ_* for possible flags and read below
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_num_msgs</term>
      <listitem><para>
   maximum number of messages per transfer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_write_len</term>
      <listitem><para>
   maximum length of a write message
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_read_len</term>
      <listitem><para>
   maximum length of a read message
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_comb_1st_msg_len</term>
      <listitem><para>
   maximum length of the first msg in a combined message
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_comb_2nd_msg_len</term>
      <listitem><para>
   maximum length of the second msg in a combined message
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Note about combined messages</title>
<para>
   Some I2C controllers can only send one message
   per transfer, plus something called combined message or write-then-read.
   This is (usually) a small write message followed by a read message and
   barely enough to access register based devices like EEPROMs. There is a flag
   to support this mode. It implies max_num_msg = 2 and does the length checks
   with max_comb_*_len because combined message mode usually has its own
   limitations. Because of HW implementations, some controllers can actually do
   write-then-anything or other variants. To support that, write-then-read has
   been broken out into smaller bits like write-first and read-second which can
   be combined as needed.
</para>
</refsect1>
</refentry>

<refentry id="API-module-i2c-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>module_i2c_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>module_i2c_driver</refname>
 <refpurpose>
     Helper macro for registering a I2C driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>module_i2c_driver </function></funcdef>
   <paramdef> <parameter>__i2c_driver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>__i2c_driver</parameter></term>
   <listitem>
    <para>
     i2c_driver struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Helper macro for I2C drivers which do not do anything special in module
   init/exit. This eliminates a lot of boilerplate. Each module may only
   use this macro once, and calling it replaces <function>module_init</function> and <function>module_exit</function>
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-register-board-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_register_board_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_register_board_info</refname>
 <refpurpose>
  statically declare I2C devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2c_register_board_info </function></funcdef>
   <paramdef>int <parameter>busnum</parameter></paramdef>
   <paramdef>struct i2c_board_info const * <parameter>info</parameter></paramdef>
   <paramdef>unsigned <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>busnum</parameter></term>
   <listitem>
    <para>
     identifies the bus to which these devices belong
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     vector of i2c device descriptors
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     how many descriptors in the vector; may be zero to reserve
     the specified bus number.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Systems using the Linux I2C driver stack can declare tables of board info
   while they initialize.  This should be done in board-specific init code
   near <function>arch_initcall</function> time, or equivalent, before any I2C adapter driver is
   registered.  For example, mainboard init code could define several devices,
   as could the init code for each daughtercard in a board stack.
   </para><para>

   The I2C devices will be created later, after the adapter for the relevant
   bus has been registered.  After that moment, standard driver model tools
   are used to bind <quote>new style</quote> I2C drivers to the devices.  The bus number
   for any device declared using this routine is not available for dynamic
   allocation.
   </para><para>

   The board info passed can safely be __initdata, but be careful of embedded
   pointers (for platform_data, functions, etc) since that won't be copied.
</para>
</refsect1>
</refentry>

<!-- drivers/i2c/i2c-core.c -->
<refentry id="API-i2c-verify-client">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_verify_client</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_verify_client</refname>
 <refpurpose>
  return parameter as i2c_client, or NULL
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-i2c-client">struct i2c_client</link> * <function>i2c_verify_client </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device, probably from some driver model iterator
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When traversing the driver model tree, perhaps using driver model
   iterators like <parameter>device_for_each_child</parameter>(), you can't assume very much
   about the nodes you find.  Use this function to avoid oopses caused
   by wrongly treating some non-I2C device as an i2c_client.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-lock-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_lock_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_lock_adapter</refname>
 <refpurpose>
     Get exclusive access to an I2C bus segment
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2c_lock_adapter </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adapter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adapter</parameter></term>
   <listitem>
    <para>
     Target I2C bus segment
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-i2c-unlock-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_unlock_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_unlock_adapter</refname>
 <refpurpose>
     Release exclusive access to an I2C bus segment
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2c_unlock_adapter </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adapter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adapter</parameter></term>
   <listitem>
    <para>
     Target I2C bus segment
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-i2c-new-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_new_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_new_device</refname>
 <refpurpose>
     instantiate an i2c device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-i2c-client">struct i2c_client</link> * <function>i2c_new_device </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adap</parameter></paramdef>
   <paramdef>struct i2c_board_info const * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adap</parameter></term>
   <listitem>
    <para>
     the adapter managing the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     describes one I2C device; bus_num is ignored
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Create an i2c device. Binding is handled through driver model
   <function>probe</function>/<function>remove</function> methods.  A driver may be bound to this device when we
   return from this function, or any later moment (e.g. maybe hotplugging will
   load the driver module).  This call is not appropriate for use by mainboard
   initialization logic, which usually runs during an <function>arch_initcall</function> long
   before any i2c_adapter could exist.
   </para><para>

   This returns the new i2c client, which may be saved for later use with
   <function><link linkend="API-i2c-unregister-device">i2c_unregister_device</link></function>; or NULL to indicate an error.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-unregister-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_unregister_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_unregister_device</refname>
 <refpurpose>
     reverse effect of <function><link linkend="API-i2c-new-device">i2c_new_device</link></function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2c_unregister_device </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">struct i2c_client</link> * <parameter>client</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     value returned from <function><link linkend="API-i2c-new-device">i2c_new_device</link></function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-new-dummy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_new_dummy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_new_dummy</refname>
 <refpurpose>
     return a new i2c device bound to a dummy driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-i2c-client">struct i2c_client</link> * <function>i2c_new_dummy </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adapter</parameter></paramdef>
   <paramdef>u16 <parameter>address</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adapter</parameter></term>
   <listitem>
    <para>
     the adapter managing the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>address</parameter></term>
   <listitem>
    <para>
     seven bit address to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns an I2C client bound to the <quote>dummy</quote> driver, intended for use
   with devices that consume multiple addresses.  Examples of such chips
   include various EEPROMS (like 24c04 and 24c08 models).
   </para><para>

   These dummy devices have two main uses.  First, most I2C and SMBus calls
   except <function><link linkend="API-i2c-transfer">i2c_transfer</link></function> need a client handle; the dummy will be that handle.
   And second, this prevents the specified address from being bound to a
   different driver.
   </para><para>

   This returns the new i2c client, which should be saved for later use with
   <function><link linkend="API-i2c-unregister-device">i2c_unregister_device</link></function>; or NULL to indicate an error.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-verify-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_verify_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_verify_adapter</refname>
 <refpurpose>
     return parameter as i2c_adapter or NULL
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2c_adapter * <function>i2c_verify_adapter </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device, probably from some driver model iterator
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When traversing the driver model tree, perhaps using driver model
   iterators like <parameter>device_for_each_child</parameter>(), you can't assume very much
   about the nodes you find.  Use this function to avoid oopses caused
   by wrongly treating some non-I2C device as an i2c_adapter.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-add-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_add_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_add_adapter</refname>
 <refpurpose>
     declare i2c adapter, use dynamic bus number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2c_add_adapter </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adapter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adapter</parameter></term>
   <listitem>
    <para>
     the adapter to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is used to declare an I2C adapter when its bus number
   doesn't matter or when its bus number is specified by an dt alias.
   Examples of bases when the bus number doesn't matter: I2C adapters
   dynamically added by USB links or PCI plugin cards.
   </para><para>

   When this returns zero, a new bus number was allocated and stored
   in adap-&gt;nr, and the specified adapter became available for clients.
   Otherwise, a negative errno value is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-add-numbered-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_add_numbered_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_add_numbered_adapter</refname>
 <refpurpose>
     declare i2c adapter, use static bus number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2c_add_numbered_adapter </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adap</parameter></term>
   <listitem>
    <para>
     the adapter to register (with adap-&gt;nr initialized)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is used to declare an I2C adapter when its bus number
   matters.  For example, use it for I2C adapters from system-on-chip CPUs,
   or otherwise built in to the system's mainboard, and where i2c_board_info
   is used to properly configure I2C devices.
   </para><para>

   If the requested bus number is set to -1, then this function will behave
   identically to i2c_add_adapter, and will dynamically assign a bus number.
   </para><para>

   If no devices have pre-been declared for this bus, then be sure to
   register the adapter before any dynamically allocated ones.  Otherwise
   the required bus ID may not be available.
   </para><para>

   When this returns zero, the specified adapter became available for
   clients using the bus number provided in adap-&gt;nr.  Also, the table
   of I2C devices pre-declared using <function><link linkend="API-i2c-register-board-info">i2c_register_board_info</link></function> is scanned,
   and the appropriate driver model device nodes are created.  Otherwise, a
   negative errno value is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-del-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_del_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_del_adapter</refname>
 <refpurpose>
     unregister I2C adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2c_del_adapter </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adap</parameter></term>
   <listitem>
    <para>
     the adapter being unregistered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This unregisters an I2C adapter which was previously registered
   by <parameter>i2c_add_adapter</parameter> or <parameter>i2c_add_numbered_adapter</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-del-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_del_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_del_driver</refname>
 <refpurpose>
     unregister I2C driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2c_del_driver </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-driver">struct i2c_driver</link> * <parameter>driver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     the driver being unregistered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-use-client">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_use_client</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_use_client</refname>
 <refpurpose>
     increments the reference count of the i2c client structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-i2c-client">struct i2c_client</link> * <function>i2c_use_client </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">struct i2c_client</link> * <parameter>client</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     the client being referenced
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each live reference to a client should be refcounted. The driver model does
   that automatically as part of driver binding, so that most drivers don't
</para>
</refsect1>
<refsect1>
<title>need to do this explicitly</title>
<para>
   they hold a reference until they're unbound
   from the device.
   </para><para>

   A pointer to the client with the incremented reference counter is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-release-client">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_release_client</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_release_client</refname>
 <refpurpose>
     release a use of the i2c client structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2c_release_client </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">struct i2c_client</link> * <parameter>client</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     the client being no longer referenced
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Must be called when a user of a client is finished with it.
</para>
</refsect1>
</refentry>

<refentry id="API---i2c-transfer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__i2c_transfer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__i2c_transfer</refname>
 <refpurpose>
     unlocked flavor of i2c_transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__i2c_transfer </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adap</parameter></paramdef>
   <paramdef>struct i2c_msg * <parameter>msgs</parameter></paramdef>
   <paramdef>int <parameter>num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adap</parameter></term>
   <listitem>
    <para>
     Handle to I2C bus
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msgs</parameter></term>
   <listitem>
    <para>
     One or more messages to execute before STOP is issued to
     terminate the operation; each message begins with a START.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num</parameter></term>
   <listitem>
    <para>
     Number of messages to be executed.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns negative errno, else the number of messages executed.
   </para><para>

   Adapter lock must be held when calling this function. No debug logging
   takes place. adap-&gt;algo-&gt;master_xfer existence isn't checked.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-transfer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_transfer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_transfer</refname>
 <refpurpose>
     execute a single or combined I2C message
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2c_transfer </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adap</parameter></paramdef>
   <paramdef>struct i2c_msg * <parameter>msgs</parameter></paramdef>
   <paramdef>int <parameter>num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adap</parameter></term>
   <listitem>
    <para>
     Handle to I2C bus
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msgs</parameter></term>
   <listitem>
    <para>
     One or more messages to execute before STOP is issued to
     terminate the operation; each message begins with a START.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num</parameter></term>
   <listitem>
    <para>
     Number of messages to be executed.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns negative errno, else the number of messages executed.
   </para><para>

   Note that there is no requirement that each message be sent to
   the same slave address, although that is the most common model.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-master-send">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_master_send</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_master_send</refname>
 <refpurpose>
     issue a single I2C message in master transmit mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2c_master_send </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">const struct i2c_client</link> * <parameter>client</parameter></paramdef>
   <paramdef>const char * <parameter>buf</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     Handle to slave device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     Data that will be written to the slave
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     How many bytes to write, must be less than 64k since msg.len is u16
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns negative errno, or else the number of bytes written.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-master-recv">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_master_recv</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_master_recv</refname>
 <refpurpose>
     issue a single I2C message in master receive mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2c_master_recv </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">const struct i2c_client</link> * <parameter>client</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     Handle to slave device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     Where to store data read from slave
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     How many bytes to read, must be less than 64k since msg.len is u16
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns negative errno, or else the number of bytes read.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-smbus-read-byte">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_smbus_read_byte</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_smbus_read_byte</refname>
 <refpurpose>
     SMBus <quote>receive byte</quote> protocol
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s32 <function>i2c_smbus_read_byte </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">const struct i2c_client</link> * <parameter>client</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     Handle to slave device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This executes the SMBus <quote>receive byte</quote> protocol, returning negative errno
   else the byte received from the device.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-smbus-write-byte">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_smbus_write_byte</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_smbus_write_byte</refname>
 <refpurpose>
     SMBus <quote>send byte</quote> protocol
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s32 <function>i2c_smbus_write_byte </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">const struct i2c_client</link> * <parameter>client</parameter></paramdef>
   <paramdef>u8 <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     Handle to slave device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     Byte to be sent
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This executes the SMBus <quote>send byte</quote> protocol, returning negative errno
   else zero on success.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-smbus-read-byte-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_smbus_read_byte_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_smbus_read_byte_data</refname>
 <refpurpose>
     SMBus <quote>read byte</quote> protocol
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s32 <function>i2c_smbus_read_byte_data </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">const struct i2c_client</link> * <parameter>client</parameter></paramdef>
   <paramdef>u8 <parameter>command</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     Handle to slave device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>command</parameter></term>
   <listitem>
    <para>
     Byte interpreted by slave
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This executes the SMBus <quote>read byte</quote> protocol, returning negative errno
   else a data byte received from the device.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-smbus-write-byte-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_smbus_write_byte_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_smbus_write_byte_data</refname>
 <refpurpose>
     SMBus <quote>write byte</quote> protocol
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s32 <function>i2c_smbus_write_byte_data </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">const struct i2c_client</link> * <parameter>client</parameter></paramdef>
   <paramdef>u8 <parameter>command</parameter></paramdef>
   <paramdef>u8 <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     Handle to slave device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>command</parameter></term>
   <listitem>
    <para>
     Byte interpreted by slave
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     Byte being written
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This executes the SMBus <quote>write byte</quote> protocol, returning negative errno
   else zero on success.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-smbus-read-word-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_smbus_read_word_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_smbus_read_word_data</refname>
 <refpurpose>
     SMBus <quote>read word</quote> protocol
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s32 <function>i2c_smbus_read_word_data </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">const struct i2c_client</link> * <parameter>client</parameter></paramdef>
   <paramdef>u8 <parameter>command</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     Handle to slave device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>command</parameter></term>
   <listitem>
    <para>
     Byte interpreted by slave
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This executes the SMBus <quote>read word</quote> protocol, returning negative errno
   else a 16-bit unsigned <quote>word</quote> received from the device.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-smbus-write-word-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_smbus_write_word_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_smbus_write_word_data</refname>
 <refpurpose>
     SMBus <quote>write word</quote> protocol
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s32 <function>i2c_smbus_write_word_data </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">const struct i2c_client</link> * <parameter>client</parameter></paramdef>
   <paramdef>u8 <parameter>command</parameter></paramdef>
   <paramdef>u16 <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     Handle to slave device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>command</parameter></term>
   <listitem>
    <para>
     Byte interpreted by slave
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     16-bit <quote>word</quote> being written
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This executes the SMBus <quote>write word</quote> protocol, returning negative errno
   else zero on success.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-smbus-read-block-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_smbus_read_block_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_smbus_read_block_data</refname>
 <refpurpose>
     SMBus <quote>block read</quote> protocol
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s32 <function>i2c_smbus_read_block_data </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">const struct i2c_client</link> * <parameter>client</parameter></paramdef>
   <paramdef>u8 <parameter>command</parameter></paramdef>
   <paramdef>u8 * <parameter>values</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     Handle to slave device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>command</parameter></term>
   <listitem>
    <para>
     Byte interpreted by slave
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>values</parameter></term>
   <listitem>
    <para>
     Byte array into which data will be read; big enough to hold
     the data returned by the slave.  SMBus allows at most 32 bytes.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This executes the SMBus <quote>block read</quote> protocol, returning negative errno
   else the number of data bytes in the slave's response.
   </para><para>

   Note that using this function requires that the client's adapter support
   the I2C_FUNC_SMBUS_READ_BLOCK_DATA functionality.  Not all adapter drivers
   support this; its emulation through I2C messaging relies on a specific
   mechanism (I2C_M_RECV_LEN) which may not be implemented.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-smbus-write-block-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_smbus_write_block_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_smbus_write_block_data</refname>
 <refpurpose>
     SMBus <quote>block write</quote> protocol
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s32 <function>i2c_smbus_write_block_data </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">const struct i2c_client</link> * <parameter>client</parameter></paramdef>
   <paramdef>u8 <parameter>command</parameter></paramdef>
   <paramdef>u8 <parameter>length</parameter></paramdef>
   <paramdef>const u8 * <parameter>values</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     Handle to slave device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>command</parameter></term>
   <listitem>
    <para>
     Byte interpreted by slave
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     Size of data block; SMBus allows at most 32 bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>values</parameter></term>
   <listitem>
    <para>
     Byte array which will be written.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This executes the SMBus <quote>block write</quote> protocol, returning negative errno
   else zero on success.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-smbus-xfer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_smbus_xfer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_smbus_xfer</refname>
 <refpurpose>
     execute SMBus protocol operations
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s32 <function>i2c_smbus_xfer </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adapter</parameter></paramdef>
   <paramdef>u16 <parameter>addr</parameter></paramdef>
   <paramdef>unsigned short <parameter>flags</parameter></paramdef>
   <paramdef>char <parameter>read_write</parameter></paramdef>
   <paramdef>u8 <parameter>command</parameter></paramdef>
   <paramdef>int <parameter>protocol</parameter></paramdef>
   <paramdef>union i2c_smbus_data * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adapter</parameter></term>
   <listitem>
    <para>
     Handle to I2C bus
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Address of SMBus slave on that bus
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     I2C_CLIENT_* flags (usually zero or I2C_CLIENT_PEC)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>read_write</parameter></term>
   <listitem>
    <para>
     I2C_SMBUS_READ or I2C_SMBUS_WRITE
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>command</parameter></term>
   <listitem>
    <para>
     Byte interpreted by slave, for protocols which use such bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>protocol</parameter></term>
   <listitem>
    <para>
     SMBus protocol operation to execute, such as I2C_SMBUS_PROC_CALL
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     Data to be read or written
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This executes an SMBus protocol operation, and returns a negative
   errno code else zero on success.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-smbus-read-i2c-block-data-or-emulated">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_smbus_read_i2c_block_data_or_emulated</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_smbus_read_i2c_block_data_or_emulated</refname>
 <refpurpose>
     read block or emulate
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s32 <function>i2c_smbus_read_i2c_block_data_or_emulated </function></funcdef>
   <paramdef><link linkend="API-struct-i2c-client">const struct i2c_client</link> * <parameter>client</parameter></paramdef>
   <paramdef>u8 <parameter>command</parameter></paramdef>
   <paramdef>u8 <parameter>length</parameter></paramdef>
   <paramdef>u8 * <parameter>values</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     Handle to slave device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>command</parameter></term>
   <listitem>
    <para>
     Byte interpreted by slave
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     Size of data block; SMBus allows at most I2C_SMBUS_BLOCK_MAX bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>values</parameter></term>
   <listitem>
    <para>
     Byte array into which data will be read; big enough to hold
     the data returned by the slave.  SMBus allows at most
     I2C_SMBUS_BLOCK_MAX bytes.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This executes the SMBus <quote>block read</quote> protocol if supported by the adapter.
   If block read is not supported, it emulates it using either word or byte
   read protocols depending on availability.
   </para><para>

   The addresses of the I2C slave device that are accessed with this function
   must be mapped to a linear region, so that a block read will have the same
   effect as a byte read. Before using this function you must double-check
   if the I2C slave does support exchanging a block transfer with a byte
   transfer.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="hsi">
     <title>High Speed Synchronous Serial Interface (HSI)</title>

     <para>
	High Speed Synchronous Serial Interface (HSI) is a
	serial interface mainly used for connecting application
	engines (APE) with cellular modem engines (CMT) in cellular
	handsets.

	HSI provides multiplexing for up to 16 logical channels,
	low-latency and full duplex communication.
     </para>

<!-- include/linux/hsi/hsi.h -->
<refentry id="API-struct-hsi-channel">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hsi_channel</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hsi_channel</refname>
 <refpurpose>
  channel resource used by the hsi clients
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hsi_channel {
  unsigned int id;
  const char * name;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>id</term>
      <listitem><para>
Channel number
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name</term>
      <listitem><para>
Channel name
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-hsi-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hsi_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hsi_config</refname>
 <refpurpose>
     Configuration for RX/TX HSI modules
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hsi_config {
  unsigned int mode;
  struct hsi_channel * channels;
  unsigned int num_channels;
  unsigned int num_hw_channels;
  unsigned int speed;
  union {unnamed_union};
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>mode</term>
      <listitem><para>
   Bit transmission mode (STREAM or FRAME)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>channels</term>
      <listitem><para>
   Channel resources used by the client
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_channels</term>
      <listitem><para>
   Number of channel resources
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_hw_channels</term>
      <listitem><para>
   Number of channels the transceiver is configured for [1..16]
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>speed</term>
      <listitem><para>
   Max bit transmission speed (Kbit/s)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>{unnamed_union}</term>
      <listitem><para>
   anonymous
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-hsi-board-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hsi_board_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hsi_board_info</refname>
 <refpurpose>
     HSI client board info
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hsi_board_info {
  const char * name;
  unsigned int hsi_id;
  unsigned int port;
  struct hsi_config tx_cfg;
  struct hsi_config rx_cfg;
  void * platform_data;
  struct dev_archdata * archdata;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name</term>
      <listitem><para>
   Name for the HSI device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>hsi_id</term>
      <listitem><para>
   HSI controller id where the client sits
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port</term>
      <listitem><para>
   Port number in the controller where the client sits
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_cfg</term>
      <listitem><para>
   HSI TX configuration
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_cfg</term>
      <listitem><para>
   HSI RX configuration
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>platform_data</term>
      <listitem><para>
   Platform related data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>archdata</term>
      <listitem><para>
   Architecture-dependent device data
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-hsi-client">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hsi_client</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hsi_client</refname>
 <refpurpose>
     HSI client attached to an HSI port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hsi_client {
  struct device device;
  struct hsi_config tx_cfg;
  struct hsi_config rx_cfg;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>device</term>
      <listitem><para>
   Driver model representation of the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_cfg</term>
      <listitem><para>
   HSI TX configuration
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_cfg</term>
      <listitem><para>
   HSI RX configuration
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-hsi-client-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hsi_client_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hsi_client_driver</refname>
 <refpurpose>
     Driver associated to an HSI client
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hsi_client_driver {
  struct device_driver driver;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>driver</term>
      <listitem><para>
   Driver model representation of the driver
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-hsi-msg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hsi_msg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hsi_msg</refname>
 <refpurpose>
     HSI message descriptor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hsi_msg {
  struct list_head link;
  struct hsi_client * cl;
  struct sg_table sgt;
  void * context;
  void (* complete) (struct hsi_msg *msg);
  void (* destructor) (struct hsi_msg *msg);
  int status;
  unsigned int actual_len;
  unsigned int channel;
  unsigned int ttype:1;
  unsigned int break_frame:1;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>link</term>
      <listitem><para>
   Free to use by the current descriptor owner
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cl</term>
      <listitem><para>
   HSI device client that issues the transfer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sgt</term>
      <listitem><para>
   Head of the scatterlist array
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>context</term>
      <listitem><para>
   Client context data associated to the transfer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>complete</term>
      <listitem><para>
   Transfer completion callback
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>destructor</term>
      <listitem><para>
   Destructor to free resources when flushing
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>status</term>
      <listitem><para>
   Status of the transfer when completed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>actual_len</term>
      <listitem><para>
   Actual length of data transferred on completion
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>channel</term>
      <listitem><para>
   Channel were to TX/RX the message
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ttype</term>
      <listitem><para>
   Transfer type (TX if set, RX otherwise)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>break_frame</term>
      <listitem><para>
   if true HSI will send/receive a break frame. Data buffers are
   ignored in the request.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-hsi-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hsi_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hsi_port</refname>
 <refpurpose>
     HSI port device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hsi_port {
  struct device device;
  struct hsi_config tx_cfg;
  struct hsi_config rx_cfg;
  unsigned int num;
  unsigned int shared:1;
  int claimed;
  struct mutex lock;
  int (* async) (struct hsi_msg *msg);
  int (* setup) (struct hsi_client *cl);
  int (* flush) (struct hsi_client *cl);
  int (* start_tx) (struct hsi_client *cl);
  int (* stop_tx) (struct hsi_client *cl);
  int (* release) (struct hsi_client *cl);
  struct atomic_notifier_head n_head;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>device</term>
      <listitem><para>
   Driver model representation of the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_cfg</term>
      <listitem><para>
   Current TX path configuration
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_cfg</term>
      <listitem><para>
   Current RX path configuration
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num</term>
      <listitem><para>
   Port number
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>shared</term>
      <listitem><para>
   Set when port can be shared by different clients
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>claimed</term>
      <listitem><para>
   Reference count of clients which claimed the port
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
   Serialize port claim
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>async</term>
      <listitem><para>
   Asynchronous transfer callback
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>setup</term>
      <listitem><para>
   Callback to set the HSI client configuration
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flush</term>
      <listitem><para>
   Callback to clean the HW state and destroy all pending transfers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start_tx</term>
      <listitem><para>
   Callback to inform that a client wants to TX data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>stop_tx</term>
      <listitem><para>
   Callback to inform that a client no longer wishes to TX data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>release</term>
      <listitem><para>
   Callback to inform that a client no longer uses the port
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>n_head</term>
      <listitem><para>
   Notifier chain for signaling port events to the clients.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-hsi-controller">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hsi_controller</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hsi_controller</refname>
 <refpurpose>
     HSI controller device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hsi_controller {
  struct device device;
  struct module * owner;
  unsigned int id;
  unsigned int num_ports;
  struct hsi_port ** port;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>device</term>
      <listitem><para>
   Driver model representation of the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>owner</term>
      <listitem><para>
   Pointer to the module owning the controller
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id</term>
      <listitem><para>
   HSI controller ID
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_ports</term>
      <listitem><para>
   Number of ports in the HSI controller
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port</term>
      <listitem><para>
   Array of HSI ports
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-hsi-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_id</refname>
 <refpurpose>
     Get HSI controller ID associated to a client
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>hsi_id </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     Pointer to a HSI client
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return the controller id where the client is attached to
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-port-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_port_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_port_id</refname>
 <refpurpose>
     Gets the port number a client is attached to
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>hsi_port_id </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     Pointer to HSI client
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return the port number associated to the client
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-setup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_setup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_setup</refname>
 <refpurpose>
     Configure the client's port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_setup </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     Pointer to the HSI client
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When sharing ports, clients should either relay on a single
   client setup or have the same setup for all of them.
   </para><para>

   Return -errno on failure, 0 on success
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_flush</refname>
 <refpurpose>
     Flush all pending transactions on the client's port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_flush </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     Pointer to the HSI client
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will destroy all pending hsi_msg in the port and reset
   the HW port so it is ready to receive and transmit from a clean state.
   </para><para>

   Return -errno on failure, 0 on success
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-async-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_async_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_async_read</refname>
 <refpurpose>
     Submit a read transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_async_read </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
   <paramdef><link linkend="API-struct-hsi-msg">struct hsi_msg</link> * <parameter>msg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     Pointer to the HSI client
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     HSI message descriptor of the transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return -errno on failure, 0 on success
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-async-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_async_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_async_write</refname>
 <refpurpose>
     Submit a write transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_async_write </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
   <paramdef><link linkend="API-struct-hsi-msg">struct hsi_msg</link> * <parameter>msg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     Pointer to the HSI client
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     HSI message descriptor of the transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return -errno on failure, 0 on success
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-start-tx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_start_tx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_start_tx</refname>
 <refpurpose>
     Signal the port that the client wants to start a TX
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_start_tx </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     Pointer to the HSI client
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return -errno on failure, 0 on success
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-stop-tx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_stop_tx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_stop_tx</refname>
 <refpurpose>
     Signal the port that the client no longer wants to transmit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_stop_tx </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     Pointer to the HSI client
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return -errno on failure, 0 on success
</para>
</refsect1>
</refentry>

<!-- drivers/hsi/hsi.c -->
<refentry id="API-hsi-port-unregister-clients">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_port_unregister_clients</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_port_unregister_clients</refname>
 <refpurpose>
  Unregister an HSI port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hsi_port_unregister_clients </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-port">struct hsi_port</link> * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     The HSI port to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-hsi-unregister-controller">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_unregister_controller</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_unregister_controller</refname>
 <refpurpose>
     Unregister an HSI controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hsi_unregister_controller </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-controller">struct hsi_controller</link> * <parameter>hsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hsi</parameter></term>
   <listitem>
    <para>
     The HSI controller to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-hsi-register-controller">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_register_controller</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_register_controller</refname>
 <refpurpose>
     Register an HSI controller and its ports
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_register_controller </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-controller">struct hsi_controller</link> * <parameter>hsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hsi</parameter></term>
   <listitem>
    <para>
     The HSI controller to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns -errno on failure, 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-register-client-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_register_client_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_register_client_driver</refname>
 <refpurpose>
     Register an HSI client to the HSI bus
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_register_client_driver </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client-driver">struct hsi_client_driver</link> * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     HSI client driver to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns -errno on failure, 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-put-controller">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_put_controller</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_put_controller</refname>
 <refpurpose>
     Free an HSI controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hsi_put_controller </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-controller">struct hsi_controller</link> * <parameter>hsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hsi</parameter></term>
   <listitem>
    <para>
     Pointer to the HSI controller to freed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   HSI controller drivers should only use this function if they need
   to free their allocated hsi_controller structures before a successful
   call to hsi_register_controller. Other use is not allowed.
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-alloc-controller">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_alloc_controller</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_alloc_controller</refname>
 <refpurpose>
     Allocate an HSI controller and its ports
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-hsi-controller">struct hsi_controller</link> * <function>hsi_alloc_controller </function></funcdef>
   <paramdef>unsigned int <parameter>n_ports</parameter></paramdef>
   <paramdef>gfp_t <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>n_ports</parameter></term>
   <listitem>
    <para>
     Number of ports on the HSI controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     Kernel allocation flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return NULL on failure or a pointer to an hsi_controller on success.
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-free-msg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_free_msg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_free_msg</refname>
 <refpurpose>
     Free an HSI message
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hsi_free_msg </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-msg">struct hsi_msg</link> * <parameter>msg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     Pointer to the HSI message
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Client is responsible to free the buffers pointed by the scatterlists.
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-alloc-msg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_alloc_msg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_alloc_msg</refname>
 <refpurpose>
     Allocate an HSI message
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-hsi-msg">struct hsi_msg</link> * <function>hsi_alloc_msg </function></funcdef>
   <paramdef>unsigned int <parameter>nents</parameter></paramdef>
   <paramdef>gfp_t <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nents</parameter></term>
   <listitem>
    <para>
     Number of memory entries
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     Kernel allocation flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   nents can be 0. This mainly makes sense for read transfer.
   In that case, HSI drivers will call the complete callback when
   there is data to be read without consuming it.
   </para><para>

   Return NULL on failure or a pointer to an hsi_msg on success.
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-async">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_async</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_async</refname>
 <refpurpose>
     Submit an HSI transfer to the controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_async </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
   <paramdef><link linkend="API-struct-hsi-msg">struct hsi_msg</link> * <parameter>msg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     HSI client sending the transfer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     The HSI transfer passed to controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The HSI message must have the channel, ttype, complete and destructor
   fields set beforehand. If nents &gt; 0 then the client has to initialize
   also the scatterlists to point to the buffers to write to or read from.
   </para><para>

   HSI controllers relay on pre-allocated buffers from their clients and they
   do not allocate buffers on their own.
   </para><para>

   Once the HSI message transfer finishes, the HSI controller calls the
   complete callback with the status and actual_len fields of the HSI message
   updated. The complete callback can be called before returning from
   hsi_async.
   </para><para>

   Returns -errno on failure or 0 on success
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-claim-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_claim_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_claim_port</refname>
 <refpurpose>
     Claim the HSI client's port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_claim_port </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
   <paramdef>unsigned int <parameter>share</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     HSI client that wants to claim its port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>share</parameter></term>
   <listitem>
    <para>
     Flag to indicate if the client wants to share the port or not.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns -errno on failure, 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-release-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_release_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_release_port</refname>
 <refpurpose>
     Release the HSI client's port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hsi_release_port </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     HSI client which previously claimed its port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-hsi-register-port-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_register_port_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_register_port_event</refname>
 <refpurpose>
     Register a client to receive port events
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_register_port_event </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
   <paramdef>void (*<parameter>handler</parameter>)
     <funcparams>struct hsi_client *, unsigned long</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     HSI client that wants to receive port events
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
     Event handler callback
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Clients should register a callback to be able to receive
   events from the ports. Registration should happen after
   claiming the port.
   The handler can be called in interrupt context.
   </para><para>

   Returns -errno on error, or 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-unregister-port-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_unregister_port_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_unregister_port_event</refname>
 <refpurpose>
     Stop receiving port events for a client
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_unregister_port_event </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     HSI client that wants to stop receiving port events
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Clients should call this function before releasing their associated
   port.
   </para><para>

   Returns -errno on error, or 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_event</refname>
 <refpurpose>
     Notifies clients about port events
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_event </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-port">struct hsi_port</link> * <parameter>port</parameter></paramdef>
   <paramdef>unsigned long <parameter>event</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     Port where the event occurred
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>event</parameter></term>
   <listitem>
    <para>
     The event type
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Clients should not be concerned about wake line behavior. However, due
   to a race condition in HSI HW protocol, clients need to be notified
   about wake line changes, so they can implement a workaround for it.
</para>
</refsect1>
<refsect1>
<title>Events</title>
<para>
   HSI_EVENT_START_RX - Incoming wake line high
   HSI_EVENT_STOP_RX - Incoming wake line down
   </para><para>

   Returns -errno on error, or 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-hsi-get-channel-id-by-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hsi_get_channel_id_by_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_get_channel_id_by_name</refname>
 <refpurpose>
     acquire channel id by channel name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hsi_get_channel_id_by_name </function></funcdef>
   <paramdef><link linkend="API-struct-hsi-client">struct hsi_client</link> * <parameter>cl</parameter></paramdef>
   <paramdef>char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cl</parameter></term>
   <listitem>
    <para>
     HSI client, which uses the channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name the channel is known under
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Clients can call this function to get the hsi channel ids similar to
   requesting IRQs or GPIOs by name. This function assumes the same
   channel configuration is used for RX and TX.
   </para><para>

   Returns -errno on error or channel id on success.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="pwm">
    <title>Pulse-Width Modulation (PWM)</title>
    <para>
      Pulse-width modulation is a modulation technique primarily used to
      control power supplied to electrical devices.
    </para>
    <para>
      The PWM framework provides an abstraction for providers and consumers
      of PWM signals. A controller that provides one or more PWM signals is
      registered as <structname><link linkend="API-struct-pwm-chip">struct pwm_chip</link></structname>. Providers are
      expected to embed this structure in a driver-specific structure. This
      structure contains fields that describe a particular chip.
    </para>
    <para>
      A chip exposes one or more PWM signal sources, each of which exposed
      as a <structname><link linkend="API-struct-pwm-device">struct pwm_device</link></structname>. Operations can be
      performed on PWM devices to control the period, duty cycle, polarity
      and active state of the signal.
    </para>
    <para>
      Note that PWM devices are exclusive resources: they can always only be
      used by one consumer at a time.
    </para>
<!-- include/linux/pwm.h -->
<refentry id="API-enum-pwm-polarity">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum pwm_polarity</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum pwm_polarity</refname>
 <refpurpose>
  polarity of a PWM signal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum pwm_polarity {
  PWM_POLARITY_NORMAL,
  PWM_POLARITY_INVERSED
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>PWM_POLARITY_NORMAL</term>
      <listitem><para>
a high signal for the duration of the duty-
cycle, followed by a low signal for the remainder of the pulse
period
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>PWM_POLARITY_INVERSED</term>
      <listitem><para>
a low signal for the duration of the duty-
cycle, followed by a high signal for the remainder of the pulse
period
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-struct-pwm-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct pwm_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct pwm_device</refname>
 <refpurpose>
     PWM channel object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct pwm_device {
  const char * label;
  unsigned long flags;
  unsigned int hwpwm;
  unsigned int pwm;
  struct pwm_chip * chip;
  void * chip_data;
  struct mutex lock;
  unsigned int period;
  unsigned int duty_cycle;
  enum pwm_polarity polarity;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>label</term>
      <listitem><para>
   name of the PWM device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   flags associated with the PWM device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>hwpwm</term>
      <listitem><para>
   per-chip relative index of the PWM device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pwm</term>
      <listitem><para>
   global index of the PWM device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>chip</term>
      <listitem><para>
   PWM chip providing this PWM device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>chip_data</term>
      <listitem><para>
   chip-private data associated with the PWM device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
   used to serialize accesses to the PWM device where necessary
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>period</term>
      <listitem><para>
   period of the PWM signal (in nanoseconds)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>duty_cycle</term>
      <listitem><para>
   duty cycle of the PWM signal (in nanoseconds)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>polarity</term>
      <listitem><para>
   polarity of the PWM signal
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-pwm-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct pwm_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct pwm_ops</refname>
 <refpurpose>
     PWM controller operations
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct pwm_ops {
  int (* request) (struct pwm_chip *chip, struct pwm_device *pwm);
  void (* free) (struct pwm_chip *chip, struct pwm_device *pwm);
  int (* config) (struct pwm_chip *chip, struct pwm_device *pwm,int duty_ns, int period_ns);
  int (* set_polarity) (struct pwm_chip *chip, struct pwm_device *pwm,enum pwm_polarity polarity);
  int (* enable) (struct pwm_chip *chip, struct pwm_device *pwm);
  void (* disable) (struct pwm_chip *chip, struct pwm_device *pwm);
#ifdef CONFIG_DEBUG_FS
  void (* dbg_show) (struct pwm_chip *chip, struct seq_file *s);
#endif
  struct module * owner;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>request</term>
      <listitem><para>
   optional hook for requesting a PWM
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>free</term>
      <listitem><para>
   optional hook for freeing a PWM
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>config</term>
      <listitem><para>
   configure duty cycles and period length for this PWM
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_polarity</term>
      <listitem><para>
   configure the polarity of this PWM
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enable</term>
      <listitem><para>
   enable PWM output toggling
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>disable</term>
      <listitem><para>
   disable PWM output toggling
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dbg_show</term>
      <listitem><para>
   optional routine to show contents in debugfs
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>owner</term>
      <listitem><para>
   helps prevent removal of modules exporting active PWMs
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-pwm-chip">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct pwm_chip</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct pwm_chip</refname>
 <refpurpose>
     abstract a PWM controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct pwm_chip {
  struct device * dev;
  struct list_head list;
  const struct pwm_ops * ops;
  int base;
  unsigned int npwm;
  struct pwm_device * pwms;
  struct pwm_device * (* of_xlate) (struct pwm_chip *pc,const struct of_phandle_args *args);
  unsigned int of_pwm_n_cells;
  bool can_sleep;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   device providing the PWMs
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>list</term>
      <listitem><para>
   list node for internal use
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ops</term>
      <listitem><para>
   callbacks for this PWM controller
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>base</term>
      <listitem><para>
   number of first PWM controlled by this chip
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>npwm</term>
      <listitem><para>
   number of PWMs controlled by this chip
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pwms</term>
      <listitem><para>
   array of PWM devices allocated by the framework
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>of_xlate</term>
      <listitem><para>
   request a PWM device given a device tree PWM specifier
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>of_pwm_n_cells</term>
      <listitem><para>
   number of cells expected in the device tree PWM specifier
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>can_sleep</term>
      <listitem><para>
   must be true if the .<function>config</function>, .<function>enable</function> or .<function>disable</function>
   operations may sleep
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- drivers/pwm/core.c -->
<refentry id="API-pwm-set-chip-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_set_chip_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_set_chip_data</refname>
 <refpurpose>
  set private chip data for a PWM
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pwm_set_chip_data </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <parameter>pwm</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pwm</parameter></term>
   <listitem>
    <para>
     PWM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     pointer to chip-specific data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pwm-get-chip-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_get_chip_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_get_chip_data</refname>
 <refpurpose>
     get private chip data for a PWM
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>pwm_get_chip_data </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <parameter>pwm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pwm</parameter></term>
   <listitem>
    <para>
     PWM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the chip-private data for the PWM device.
</para>
</refsect1>
</refentry>

<refentry id="API-pwmchip-add-with-polarity">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwmchip_add_with_polarity</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwmchip_add_with_polarity</refname>
 <refpurpose>
     register a new PWM chip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pwmchip_add_with_polarity </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-chip">struct pwm_chip</link> * <parameter>chip</parameter></paramdef>
   <paramdef><link linkend="API-enum-pwm-polarity">enum pwm_polarity </link><parameter>polarity</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>chip</parameter></term>
   <listitem>
    <para>
     the PWM chip to add
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>polarity</parameter></term>
   <listitem>
    <para>
     initial polarity of PWM channels
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register a new PWM chip. If chip-&gt;base &lt; 0 then a dynamically assigned base
   will be used. The initial polarity for all channels is specified by the
   <parameter>polarity</parameter> parameter.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pwmchip-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwmchip_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwmchip_add</refname>
 <refpurpose>
     register a new PWM chip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pwmchip_add </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-chip">struct pwm_chip</link> * <parameter>chip</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>chip</parameter></term>
   <listitem>
    <para>
     the PWM chip to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register a new PWM chip. If chip-&gt;base &lt; 0 then a dynamically assigned base
   will be used. The initial polarity for all channels is normal.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pwmchip-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwmchip_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwmchip_remove</refname>
 <refpurpose>
     remove a PWM chip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pwmchip_remove </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-chip">struct pwm_chip</link> * <parameter>chip</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>chip</parameter></term>
   <listitem>
    <para>
     the PWM chip to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes a PWM chip. This function may return busy if the PWM chip provides
   a PWM device that is still requested.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pwm-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_request</refname>
 <refpurpose>
     request a PWM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <function>pwm_request </function></funcdef>
   <paramdef>int <parameter>pwm</parameter></paramdef>
   <paramdef>const char * <parameter>label</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pwm</parameter></term>
   <listitem>
    <para>
     global PWM device index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>label</parameter></term>
   <listitem>
    <para>
     PWM device label
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is deprecated, use <function><link linkend="API-pwm-get">pwm_get</link></function> instead.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to a PWM device or an <function>ERR_PTR</function>-encoded error code on
   failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pwm-request-from-chip">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_request_from_chip</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_request_from_chip</refname>
 <refpurpose>
     request a PWM device relative to a PWM chip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <function>pwm_request_from_chip </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-chip">struct pwm_chip</link> * <parameter>chip</parameter></paramdef>
   <paramdef>unsigned int <parameter>index</parameter></paramdef>
   <paramdef>const char * <parameter>label</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>chip</parameter></term>
   <listitem>
    <para>
     PWM chip
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>index</parameter></term>
   <listitem>
    <para>
     per-chip index of the PWM to request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>label</parameter></term>
   <listitem>
    <para>
     a literal description string of this PWM
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the PWM device at the given index of the given PWM
   chip. A negative error code is returned if the index is not valid for the
   specified PWM chip or if the PWM device cannot be requested.
</para>
</refsect1>
</refentry>

<refentry id="API-pwm-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_free</refname>
 <refpurpose>
     free a PWM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pwm_free </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <parameter>pwm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pwm</parameter></term>
   <listitem>
    <para>
     PWM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is deprecated, use <function><link linkend="API-pwm-put">pwm_put</link></function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-pwm-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_config</refname>
 <refpurpose>
     change a PWM device configuration
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pwm_config </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <parameter>pwm</parameter></paramdef>
   <paramdef>int <parameter>duty_ns</parameter></paramdef>
   <paramdef>int <parameter>period_ns</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pwm</parameter></term>
   <listitem>
    <para>
     PWM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>duty_ns</parameter></term>
   <listitem>
    <para>
     "on" time (in nanoseconds)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>period_ns</parameter></term>
   <listitem>
    <para>
     duration (in nanoseconds) of one cycle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pwm-set-polarity">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_set_polarity</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_set_polarity</refname>
 <refpurpose>
     configure the polarity of a PWM signal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pwm_set_polarity </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <parameter>pwm</parameter></paramdef>
   <paramdef><link linkend="API-enum-pwm-polarity">enum pwm_polarity </link><parameter>polarity</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pwm</parameter></term>
   <listitem>
    <para>
     PWM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>polarity</parameter></term>
   <listitem>
    <para>
     new polarity of the PWM signal
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that the polarity cannot be configured while the PWM device is
   enabled.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pwm-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_enable</refname>
 <refpurpose>
     start a PWM output toggling
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pwm_enable </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <parameter>pwm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pwm</parameter></term>
   <listitem>
    <para>
     PWM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pwm-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_disable</refname>
 <refpurpose>
     stop a PWM output toggling
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pwm_disable </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <parameter>pwm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pwm</parameter></term>
   <listitem>
    <para>
     PWM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-of-pwm-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>of_pwm_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>of_pwm_get</refname>
 <refpurpose>
     request a PWM via the PWM framework
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <function>of_pwm_get </function></funcdef>
   <paramdef>struct device_node * <parameter>np</parameter></paramdef>
   <paramdef>const char * <parameter>con_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>np</parameter></term>
   <listitem>
    <para>
     device node to get the PWM from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>con_id</parameter></term>
   <listitem>
    <para>
     consumer name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the PWM device parsed from the phandle and index specified in the
   <quote>pwms</quote> property of a device tree node or a negative error-code on failure.
   Values parsed from the device tree are stored in the returned PWM device
   object.
   </para><para>

   If con_id is NULL, the first PWM device listed in the <quote>pwms</quote> property will
   be requested. Otherwise the <quote>pwm-names</quote> property is used to do a reverse
   lookup of the PWM index. This also means that the <quote>pwm-names</quote> property
   becomes mandatory for devices that look up the PWM device via the con_id
   parameter.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the requested PWM device or an <function>ERR_PTR</function>-encoded
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pwm-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_get</refname>
 <refpurpose>
     look up and request a PWM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <function>pwm_get </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const char * <parameter>con_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device for PWM consumer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>con_id</parameter></term>
   <listitem>
    <para>
     consumer name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Lookup is first attempted using DT. If the device was not instantiated from
   a device tree, a PWM chip and a relative index is looked up via a table
   supplied by board setup code (see <function>pwm_add_table</function>).
   </para><para>

   Once a PWM chip has been found the specified PWM device will be requested
   and is ready to be used.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the requested PWM device or an <function>ERR_PTR</function>-encoded
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pwm-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_put</refname>
 <refpurpose>
     release a PWM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pwm_put </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <parameter>pwm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pwm</parameter></term>
   <listitem>
    <para>
     PWM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-devm-pwm-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_pwm_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_pwm_get</refname>
 <refpurpose>
     resource managed <function><link linkend="API-pwm-get">pwm_get</link></function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <function>devm_pwm_get </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>const char * <parameter>con_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device for PWM consumer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>con_id</parameter></term>
   <listitem>
    <para>
     consumer name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function performs like <function><link linkend="API-pwm-get">pwm_get</link></function> but the acquired PWM device will
   automatically be released on driver detach.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the requested PWM device or an <function>ERR_PTR</function>-encoded
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-of-pwm-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_of_pwm_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_of_pwm_get</refname>
 <refpurpose>
     resource managed <function><link linkend="API-of-pwm-get">of_pwm_get</link></function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <function>devm_of_pwm_get </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef>struct device_node * <parameter>np</parameter></paramdef>
   <paramdef>const char * <parameter>con_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device for PWM consumer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>np</parameter></term>
   <listitem>
    <para>
     device node to get the PWM from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>con_id</parameter></term>
   <listitem>
    <para>
     consumer name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function performs like <function><link linkend="API-of-pwm-get">of_pwm_get</link></function> but the acquired PWM device will
   automatically be released on driver detach.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the requested PWM device or an <function>ERR_PTR</function>-encoded
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-pwm-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_pwm_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_pwm_put</refname>
 <refpurpose>
     resource managed <function><link linkend="API-pwm-put">pwm_put</link></function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>devm_pwm_put </function></funcdef>
   <paramdef><link linkend="API-struct-device">struct device</link> * <parameter>dev</parameter></paramdef>
   <paramdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <parameter>pwm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device for PWM consumer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pwm</parameter></term>
   <listitem>
    <para>
     PWM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release a PWM previously allocated using <function><link linkend="API-devm-pwm-get">devm_pwm_get</link></function>. Calling this
   function is usually not needed because devm-allocated resources are
   automatically released on driver detach.
</para>
</refsect1>
</refentry>

<refentry id="API-pwm-can-sleep">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pwm_can_sleep</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pwm_can_sleep</refname>
 <refpurpose>
     report whether PWM access will sleep
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>pwm_can_sleep </function></funcdef>
   <paramdef><link linkend="API-struct-pwm-device">struct pwm_device</link> * <parameter>pwm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pwm</parameter></term>
   <listitem>
    <para>
     PWM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if accessing the PWM can sleep, false otherwise.
</para>
</refsect1>
</refentry>

  </chapter>

</book>