xref: /linux-4.1.27/Documentation/DocBook/device-drivers.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 id="API-module-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>module_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>module_init</refname>
 <refpurpose>
  driver initialization entry point
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>module_init </function></funcdef>
   <paramdef> <parameter>x</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     function to be run at kernel boot time or module insertion
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>module_init</function> will either be called during <function>do_initcalls</function> (if
   builtin) or at module insertion time (if a module).  There can only
   be one per module.
</para>
</refsect1>
</refentry>

<refentry id="API-module-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>module_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>module_exit</refname>
 <refpurpose>
     driver exit entry point
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>module_exit </function></funcdef>
   <paramdef> <parameter>x</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     function to be run when driver is removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>module_exit</function> will wrap the driver clean-up code
   with <function>cleanup_module</function> when used with rmmod when
   the driver is a module.  If the driver is statically
   compiled into the kernel, <function>module_exit</function> has no effect.
   There can only be one per module.
</para>
</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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-cputime">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct cputime</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct cputime</refname>
 <refpurpose>
  snaphsot of system and user cputime
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct cputime {
  cputime_t utime;
  cputime_t stime;
};  </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>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Gathers a generic snapshot of user and system time.
</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.1.27</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 is an extension of struct cputime that includes the total runtime
   spent by the task from the scheduler point of view.
   </para><para>

   As a result, 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.1.27</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 cputime;
  int running;
  raw_spinlock_t lock;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>cputime</term>
      <listitem><para>
   thread group interval timers.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>running</term>
      <listitem><para>
   non-zero when there are timers running and
   <parameter>cputime</parameter> receives updates.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
   lock for fields in this struct.
      </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.1.27</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>is_global_init</refname>
 <refpurpose>
     check if a task structure is init
 </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.1.27</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.1.27</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-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>threadgroup_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>threadgroup_lock</refname>
 <refpurpose>
     lock threadgroup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>threadgroup_lock </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>
     member task of the threadgroup to lock
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Lock the threadgroup <parameter>tsk</parameter> belongs to.  No new task is allowed to enter
   and member tasks aren't allowed to exit (as indicated by PF_EXITING) or
   change -&gt;group_leader/pid.  This is useful for cases where the threadgroup
   needs to stay stable across blockable operations.
   </para><para>

   fork and exit paths explicitly call threadgroup_change_{begin|end}() for
   synchronization.  While held, no new task will be added to threadgroup
   and no existing live task will have its PF_EXITING set.
   </para><para>

   <function>de_thread</function> does threadgroup_change_{begin|end}() when a non-leader
   sub-thread becomes a new leader.
</para>
</refsect1>
</refentry>

<refentry id="API-threadgroup-unlock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>threadgroup_unlock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>threadgroup_unlock</refname>
 <refpurpose>
     unlock threadgroup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>threadgroup_unlock </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>
     member task of the threadgroup to unlock
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reverse <function>threadgroup_lock</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.1.27</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.1.27</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.1.27</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 safe to call from within a preemption notifier.
</para>
</refsect1>
</refentry>

<refentry id="API-preempt-schedule-context">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>preempt_schedule_context</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>preempt_schedule_context</refname>
 <refpurpose>
     preempt_schedule called by tracing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__visible void __sched notrace <function>preempt_schedule_context </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.1.27</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-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.1.27</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>yield</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>yield</function>;
   </para><para>

   where one assumes that <function>yield</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>yield</function> as a progress guarantee!!
   </para><para>

   If you want to use <function>yield</function> to wait for something, use <function>wait_event</function>.
   If you want to use <function>yield</function> to be 'nice' for others, use <function>cond_resched</function>.
   If you still want to use <function>yield</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>__round_jiffies</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.1.27</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>__round_jiffies_relative</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.1.27</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>round_jiffies</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.1.27</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>round_jiffies_relative</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.1.27</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>__round_jiffies</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.1.27</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>__round_jiffies_relative</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.1.27</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>round_jiffies</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.1.27</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>round_jiffies_relative</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.1.27</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>mod_timer</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.1.27</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>init_timer_key</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.1.27</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>mod_timer_pending</function> is the same for pending timers as <function>mod_timer</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.1.27</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>mod_timer</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>mod_timer</function> is the only safe way to modify the timeout,
   since <function>add_timer</function> cannot modify an already running timer.
   </para><para>

   The function returns whether it has modified a pending timer or not.
   (ie. <function>mod_timer</function> of an inactive timer returns 0, <function>mod_timer</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.1.27</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>mod_timer_pinned</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.1.27</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.1.27</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.1.27</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>del_timer</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>del_timer</function> of an inactive timer returns 0, <function>del_timer</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.1.27</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.1.27</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>del_timer</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>add_timer_on</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>del_timer_sync</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.1.27</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.1.27</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.1.27</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.1.27</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 <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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>void * <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>wait_on_bit</function> in threads waiting for the bit to clear.
   One uses <function>wait_on_bit</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.1.27</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>void * <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>wait_on_bit</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.1.27</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>void * <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>wait_on_bit</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.1.27</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>void * <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>wait_on_bit</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.1.27</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>void * <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>wait_on_bit</function> in threads waiting to be able to set the bit.
   One uses <function>wait_on_bit_lock</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.1.27</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>void * <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>wait_on_bit</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.1.27</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>void * <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>wait_on_bit</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>wake_up_bit</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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;
  unsigned long state;
#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>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>hrtimer_init</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.1.27</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.1.27</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 resolution;
  ktime_t (* get_time) (void);
  ktime_t softirq_time;
  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>resolution</term>
      <listitem><para>
   the resolution of the clock, in nanoseconds
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_time</term>
      <listitem><para>
   function to retrieve the current time of the clock
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>softirq_time</term>
      <listitem><para>
   the time when running the hrtimer queue in the softirq
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>offset</term>
      <listitem><para>
   offset of this clock to the monotonic base
      </para></listitem>
    </varlistentry>
  </variablelist>
 </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.1.27</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>struct hrtimer * <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>
</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.1.27</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>int <function>hrtimer_start_range_ns </function></funcdef>
   <paramdef>struct hrtimer * <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>
<refsect1>
<title>Returns</title>
<para>
   0 on success
   1 when the timer was active
</para>
</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.1.27</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>int <function>hrtimer_start </function></funcdef>
   <paramdef>struct hrtimer * <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>
<refsect1>
<title>Returns</title>
<para>
   0 on success
   1 when the timer was active
</para>
</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.1.27</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>struct hrtimer * <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.1.27</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>struct hrtimer * <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.1.27</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>const struct hrtimer * <parameter>timer</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>
 </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.1.27</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>struct hrtimer * <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-hrtimer-get-res">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hrtimer_get_res</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hrtimer_get_res</refname>
 <refpurpose>
     get the timer resolution for a clock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hrtimer_get_res </function></funcdef>
   <paramdef>const clockid_t <parameter>which_clock</parameter></paramdef>
   <paramdef>struct timespec * <parameter>tp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>which_clock</parameter></term>
   <listitem>
    <para>
     which clock to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tp</parameter></term>
   <listitem>
    <para>
     pointer to timespec variable to store the resolution
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Store the resolution of the clock selected by <parameter>which_clock</parameter> in the
   variable pointed to by <parameter>tp</parameter>.
</para>
</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.1.27</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 "<parameter>expires</parameter>+<parameter>delta</parameter>",
   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.1.27</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>
<!-- 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.1.27</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.1.27</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.1.27</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>queue_delayed_work_on</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.1.27</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.1.27</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 detemined
   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.1.27</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>flush_work</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.1.27</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>cancel_delayed_work_sync</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.1.27</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>flush_work</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>flush_work</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.1.27</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>cancel_delayed_work_sync</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.1.27</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>cancel_work_sync</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-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.1.27</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>cancel_delayed_work_sync</function> or
   <function>cancel_work_sync</function> instead.
</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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 int <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.1.27</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.1.27</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 int <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>task_clear_jobctl_trapping</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>wake_up_process</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.1.27</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>kthread_stop</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>kthread_stop</function>.
</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.1.27</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>kthread_should_stop</function> for freezable kthreads, which will enter
   refrigerator if necessary.  This function is safe from <function>kthread_stop</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.1.27</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>
     memory node number.
    </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>wake_up_process</function> to start
   it.  See also <function>kthread_run</function>.
   </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 -1.
   When woken, the thread will run @<function>threadfn</function> with <parameter>data</parameter> as its
   argument. @<function>threadfn</function> can either call <function>do_exit</function> directly if it is a
   standalone thread for which no one will call <function>kthread_stop</function>, or
   return when '<function>kthread_should_stop</function>' is true (which means
   <function>kthread_stop</function> has been called).  The return value should be zero
   or a negative error number; it will be passed to <function>kthread_stop</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.1.27</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-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.1.27</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>kthread_should_stop</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>wake_up_process</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>wake_up_process</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.1.27</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>kthread_run</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>kthread_stop</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>kobject_rename</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.1.27</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>kobject_add</function> call.
   </para><para>

   After this function is called, the kobject MUST be cleaned up by a call
   to <function>kobject_put</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.1.27</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>kobject_put</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.1.27</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>kobject_init</function> and
   <function>kobject_add</function>.  The same type of error handling after a call to
   <function>kobject_add</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.1.27</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-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.1.27</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.1.27</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.1.27</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.1.27</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>kobject_put</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.1.27</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.1.27</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.1.27</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>kset_unregister</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.1.27</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.1.27</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.1.27</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-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.1.27</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.1.27</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.1.27</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.1.27</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>trace_printk</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>trace_puts</function> will suffice. But how can we take advantage of
   using <function>trace_puts</function> when <function>trace_printk</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>trace_puts</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.1.27</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>trace_printk</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>trace_puts</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>printk</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>console_unlock</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>printk</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.1.27</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.1.27</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.1.27</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>printk</function>.  If this is the case, <function>console_unlock</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>console_unlock</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.1.27</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>console_lock</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.1.27</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>printk_timed_ratelimit</function> returns true if more than <parameter>interval_msecs</parameter>
   milliseconds have elapsed since the last time <function>printk_timed_ratelimit</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>kmsg_dump_get_line</function> and
   <function>kmsg_dump_get_buffer</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.1.27</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.1.27</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.1.27</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.1.27</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>init_srcu_struct</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.1.27</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>synchronize_srcu</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>synchronize_srcu</function> from the corresponding
   SRCU read-side critical section; doing so will result in deadlock.
   However, it is perfectly legal to call <function>synchronize_srcu</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>synchronize_srcu</function>.
   On systems with more than one CPU, when <function>synchronize_srcu</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>synchronize_srcu</function>.  In addition,
   each CPU having an SRCU read-side critical section that extends beyond
   the return from <function>synchronize_srcu</function> is guaranteed to have executed a
   full memory barrier after the beginning of <function>synchronize_srcu</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>synchronize_srcu</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>synchronize_srcu</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>synchronize_srcu</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.1.27</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>synchronize_srcu_expedited</function> has the same deadlock and
   memory-ordering properties as does <function>synchronize_srcu</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>synchronize_sched</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>synchronize_sched</function>.  In addition, each CPU having
   an RCU read-side critical section that extends beyond the return from
   <function>synchronize_sched</function> is guaranteed to have executed a full memory barrier
   after the beginning of <function>synchronize_sched</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>synchronize_sched</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>synchronize_sched</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>synchronize_rcu</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.1.27</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>synchronize_sched</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.1.27</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>cond_synchronize_rcu</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.1.27</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>get_state_synchronize_rcu</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>get_state_synchronize_rcu</function>, just return.  Otherwise, invoke
   <function>synchronize_rcu</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.1.27</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>synchronize_sched_expedited</function> in a loop, please
   restructure your code to batch your updates, and then use a single
   <function>synchronize_sched</function> instead.
   </para><para>

   This implementation can be thought of as an application of ticket
   locking to RCU, with sync_sched_expedited_started and
   sync_sched_expedited_done taking on the roles of the halves
   of the ticket-lock word.  Each task atomically increments
   sync_sched_expedited_started upon entry, snapshotting the old value,
   then attempts to stop all the CPUs.  If this succeeds, then each
   CPU will have executed a context switch, resulting in an RCU-sched
   grace period.  We are then done, so we use <function>atomic_cmpxchg</function> to
   update sync_sched_expedited_done to match our snapshot -- but
   only if someone else has not already advanced past our snapshot.
   </para><para>

   On the other hand, if <function>try_stop_cpus</function> fails, we check the value
   of sync_sched_expedited_done.  If it has advanced past our
   initial snapshot, then someone else must have forced a grace period
   some time after we took our snapshot.  In this case, our work is
   done for us, and we can simply return.  Otherwise, we try again,
   but keep our initial snapshot for purposes of checking for someone
   doing our work for us.
   </para><para>

   If we fail too many times in a row, we fall back to <function>synchronize_sched</function>.
</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.1.27</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.1.27</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.1.27</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>synchronize_rcu</function>, the caller might well be executing
   concurrently with new RCU read-side critical sections that began while
   <function>synchronize_rcu</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>synchronize_sched</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.1.27</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>synchronize_sched_expedited</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>synchronize_rcu_expedited</function> in a loop,
   please restructure your code to batch your updates, and then Use a
   single <function>synchronize_rcu</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.1.27</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>rcu_barrier</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-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.1.27</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>synchronize_rcu</function> and
   friends act as the corresponding <function>synchronize_rcu_expedited</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rcu_unexpedite_gp</refname>
 <refpurpose>
     Cancel prior <function>rcu_expedite_gp</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>rcu_expedite_gp</function>.  If all prior calls to
   <function>rcu_expedite_gp</function> are undone by a subsequent call to <function>rcu_unexpedite_gp</function>,
   and if the rcu_expedited sysfs/boot parameter is not set, then all
   subsequent calls to <function>synchronize_rcu</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.1.27</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.1.27</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-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.1.27</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.1.27</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>init_rcu_head_on_stack</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>init_rcu_head_on_stack</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.1.27</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>synchronize_rcu_tasks</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>synchronize_rcu_tasks</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>synchronize_rcu_tasks</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>synchronize_rcu_tasks</function>.  In addition, each CPU
   having an RCU-tasks read-side critical section that extends beyond
   the return from <function>synchronize_rcu_tasks</function> is guaranteed to have executed
   a full memory barrier after the beginning of <function>synchronize_rcu_tasks</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>synchronize_rcu_tasks</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>synchronize_rcu_tasks</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.1.27</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">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devres_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devres_alloc</refname>
 <refpurpose>
  Allocate device resource data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>devres_alloc </function></funcdef>
   <paramdef>dr_release_t <parameter>release</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>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>
 </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.1.27</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>struct device * <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.1.27</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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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>devm_add_action</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.1.27</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>struct device * <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.1.27</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>struct device * <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>devm_kmalloc</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.1.27</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>struct device * <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>devm_kmalloc</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.1.27</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>struct device * <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>devm_kmalloc</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.1.27</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>struct device * <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>devm_kmalloc</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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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>devm_get_free_pages</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.1.27</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 ("foo<constant>u</constant>", 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-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.1.27</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;
  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>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.1.27</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);
  int (* 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.1.27</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.1.27</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_PINCTRL
  struct dev_pin_info * pins;
#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>pins</term>
      <listitem><para>
   For device pin management.
   See Documentation/pinctrl.txt for details.
      </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.1.27</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>

     </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.1.27</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.1.27</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>struct device_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct device * <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.1.27</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>struct device * <function>driver_find_device </function></funcdef>
   <paramdef>struct device_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct device * <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>driver_for_each_device</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.1.27</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>struct device_driver * <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.1.27</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>struct device_driver * <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.1.27</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>struct device_driver * <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.1.27</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>struct device_driver * <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.1.27</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>struct device_driver * <function>driver_find </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct bus_type * <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.1.27</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>const struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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>device_register</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>get_device</function>/<function>put_device</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>put_device</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.1.27</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>struct device * <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.1.27</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>struct device * <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>device_register</function>, though may be called
   separately _iff_ <function>device_initialize</function> has been called separately.
   </para><para>

   This adds <parameter>dev</parameter> to the kobject hierarchy via <function>kobject_add</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>device_register</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>put_device</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.1.27</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>struct device * <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>device_initialize</function>
   and <function>device_add</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>put_device</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_device</refname>
 <refpurpose>
     increment reference count for device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct device * <function>get_device </function></funcdef>
   <paramdef>struct device * <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>kobject_get</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.1.27</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>struct device * <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.1.27</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>struct device * <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>device_add</function>, and removes it
   from the kobject hierarchy.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   this should be called manually _iff_ <function>device_add</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.1.27</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>struct device * <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>device_register</function>. First,
   we remove it from all the subsystems with <function>device_del</function>, then
   we decrement the reference count via <function>put_device</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.1.27</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>struct device * <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.1.27</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>struct device * <function>device_find_child </function></funcdef>
   <paramdef>struct device * <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>device_for_each_child</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>put_device</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__root_device_register</refname>
 <refpurpose>
     allocate and register a root device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct device * <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>device_register</function>. In order to free the returned
   device, use <function>root_device_unregister</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>struct device</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.1.27</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>struct device * <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.1.27</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>struct device * <function>device_create_vargs </function></funcdef>
   <paramdef>struct class * <parameter>class</parameter></paramdef>
   <paramdef>struct device * <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>struct device</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.1.27</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>struct device * <function>device_create </function></funcdef>
   <paramdef>struct class * <parameter>class</parameter></paramdef>
   <paramdef>struct device * <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>struct device</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.1.27</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>struct device * <function>device_create_with_groups </function></funcdef>
   <paramdef>struct class * <parameter>class</parameter></paramdef>
   <paramdef>struct device * <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>struct device</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_destroy</refname>
 <refpurpose>
     removes a device that was created with <function>device_create</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>device_destroy </function></funcdef>
   <paramdef>struct class * <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>device_create</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.1.27</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>struct device * <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.1.27</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>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct device * <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.1.27</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>struct device * <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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__class_create</refname>
 <refpurpose>
  create a struct class structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct class * <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>device_create</function>.
   </para><para>

   Returns <structname>struct class</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>class_destroy</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.1.27</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>struct class * <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.1.27</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>struct class * <parameter>class</parameter></paramdef>
   <paramdef>struct device * <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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_dev_iter_next</refname>
 <refpurpose>
     iterate to the next device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct device * <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.1.27</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.1.27</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>struct class * <parameter>class</parameter></paramdef>
   <paramdef>struct device * <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.1.27</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>struct device * <function>class_find_device </function></funcdef>
   <paramdef>struct class * <parameter>class</parameter></paramdef>
   <paramdef>struct device * <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>put_device</function> after use.
   </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-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.1.27</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.1.27</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.1.27</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>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct device * <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.1.27</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>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct device * <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.1.27</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.1.27</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>struct device * <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.1.27</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>struct device * <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>request_firmware</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.1.27</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.1.27</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>struct device * <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>request_firmware</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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.1.27</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>struct device * <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.1.27</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>struct device_driver * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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.1.27</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>struct device * <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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>platform_device_register</function>, though may be called
   separately _iff_ pdev was allocated by <function>platform_device_alloc</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.1.27</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.1.27</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.1.27</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>platform_device_put</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>

<!-- 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.1.27</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>struct bus_type * <parameter>bus</parameter></paramdef>
   <paramdef>struct device * <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.1.27</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>struct device * <function>bus_find_device </function></funcdef>
   <paramdef>struct bus_type * <parameter>bus</parameter></paramdef>
   <paramdef>struct device * <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>bus_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>
</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.1.27</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>struct device * <function>bus_find_device_by_name </function></funcdef>
   <paramdef>struct bus_type * <parameter>bus</parameter></paramdef>
   <paramdef>struct device * <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>bus_find_device</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.1.27</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>struct device * <function>subsys_find_device_by_id </function></funcdef>
   <paramdef>struct bus_type * <parameter>subsys</parameter></paramdef>
   <paramdef>unsigned int <parameter>id</parameter></paramdef>
   <paramdef>struct device * <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.1.27</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>struct bus_type * <parameter>bus</parameter></paramdef>
   <paramdef>struct device_driver * <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.1.27</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>struct bus_type * <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>device_attach</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.1.27</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>struct device * <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.1.27</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>struct bus_type * <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.1.27</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>struct bus_type * <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.1.27</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>struct bus_type * <parameter>subsys</parameter></paramdef>
   <paramdef>struct device * <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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>subsys_dev_iter_next</refname>
 <refpurpose>
     iterate to the next device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct device * <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.1.27</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.1.27</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>struct bus_type * <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.1.27</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>struct bus_type * <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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>struct device * <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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>struct fence * <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>fence_wait</function> calls and run all the callbacks added with
   <function>fence_add_callback</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.1.27</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>struct fence * <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>fence_wait</function> calls and run all the callbacks added with
   <function>fence_add_callback</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.1.27</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>struct fence * <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.1.27</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>struct fence * <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.1.27</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>struct fence * <parameter>fence</parameter></paramdef>
   <paramdef>struct fence_cb * <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.1.27</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>struct fence * <parameter>fence</parameter></paramdef>
   <paramdef>struct fence_cb * <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.1.27</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>struct fence * <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-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.1.27</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>struct fence * <parameter>fence</parameter></paramdef>
   <paramdef>const struct fence_ops * <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.1.27</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>fence_context_alloc</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.1.27</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.1.27</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_get</refname>
 <refpurpose>
     increases refcount of the fence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct fence * <function>fence_get </function></funcdef>
   <paramdef>struct fence * <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.1.27</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>struct fence * <function>fence_get_rcu </function></funcdef>
   <paramdef>struct fence * <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.1.27</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>struct fence * <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.1.27</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>struct fence * <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.1.27</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>struct fence * <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-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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fence_later</refname>
 <refpurpose>
     return the chronologically later fence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct fence * <function>fence_later </function></funcdef>
   <paramdef>struct fence * <parameter>f1</parameter></paramdef>
   <paramdef>struct fence * <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.1.27</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>struct fence * <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.1.27</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>struct fence * <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.1.27</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>const struct fence_ops * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>struct device * <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>dmam_release_declared_memory</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>struct device * <parameter>subordinate</parameter></paramdef>
   <paramdef>struct device * <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.1.27</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-match-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acpi_match_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acpi_match_device</refname>
 <refpurpose>
  Match a struct device against a given list of ACPI IDs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct acpi_device_id * <function>acpi_match_device </function></funcdef>
   <paramdef>const struct acpi_device_id * <parameter>ids</parameter></paramdef>
   <paramdef>const struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     Array of struct acpi_device_id object to match against.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     The device structure to match.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check if <parameter>dev</parameter> has a valid ACPI handle and if there is a struct acpi_device
   object for that handle and use that object to match against a given list of
   device IDs.
   </para><para>

   Return a pointer to the first matching ID on success or <constant>NULL</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-acpi-bus-register-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acpi_bus_register_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acpi_bus_register_driver</refname>
 <refpurpose>
     register a driver with the ACPI bus
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>acpi_bus_register_driver </function></funcdef>
   <paramdef>struct acpi_driver * <parameter>driver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     driver being registered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers a driver with the ACPI bus.  Searches the namespace for all
   devices that match the driver's criteria and binds.  Returns zero for
   success or a negative error status for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-acpi-bus-unregister-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acpi_bus_unregister_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acpi_bus_unregister_driver</refname>
 <refpurpose>
     unregisters a driver with the ACPI bus
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>acpi_bus_unregister_driver </function></funcdef>
   <paramdef>struct acpi_driver * <parameter>driver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     driver to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregisters a driver with the ACPI bus.  Searches the namespace for all
   devices that match the driver's criteria and unbinds.
</para>
</refsect1>
</refentry>

<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.1.27</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.1.27</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-create-pnp-modalias">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>create_pnp_modalias</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>create_pnp_modalias</refname>
 <refpurpose>
  Create hid/cid(s) string for modalias and uevent
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>create_pnp_modalias </function></funcdef>
   <paramdef>struct acpi_device * <parameter>acpi_dev</parameter></paramdef>
   <paramdef>char * <parameter>modalias</parameter></paramdef>
   <paramdef>int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>acpi_dev</parameter></term>
   <listitem>
    <para>
     ACPI device object.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>modalias</parameter></term>
   <listitem>
    <para>
     Buffer to print into.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Size of the buffer.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates hid/cid(s) string needed for modalias and uevent
   e.g. on a device with hid:IBM0001 and cid:ACPI0001 you get:
</para>
</refsect1>
<refsect1>
<title>modalias</title>
<para>
   "acpi:IBM0001:ACPI0001"
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0: no _HID and no _CID
   -EINVAL: output error
   -ENOMEM: output is truncated
</para>
</refsect1>
</refentry>

<refentry id="API-create-of-modalias">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>create_of_modalias</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>create_of_modalias</refname>
 <refpurpose>
     Creates DT compatible string for modalias and uevent
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>create_of_modalias </function></funcdef>
   <paramdef>struct acpi_device * <parameter>acpi_dev</parameter></paramdef>
   <paramdef>char * <parameter>modalias</parameter></paramdef>
   <paramdef>int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>acpi_dev</parameter></term>
   <listitem>
    <para>
     ACPI device object.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>modalias</parameter></term>
   <listitem>
    <para>
     Buffer to print into.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Size of the buffer.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Expose DT compatible modalias as of</title>
<para>
   NnameTCcompatible.  This function should
   only be called for devices having PRP0001 in their list of ACPI/PNP IDs.
</para>
</refsect1>
</refentry>

<refentry id="API-acpi-of-match-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acpi_of_match_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acpi_of_match_device</refname>
 <refpurpose>
     Match device object using the <quote>compatible</quote> property.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>acpi_of_match_device </function></funcdef>
   <paramdef>struct acpi_device * <parameter>adev</parameter></paramdef>
   <paramdef>const struct of_device_id * <parameter>of_match_table</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adev</parameter></term>
   <listitem>
    <para>
     ACPI device object to match.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>of_match_table</parameter></term>
   <listitem>
    <para>
     List of device IDs to match against.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If <parameter>dev</parameter> has an ACPI companion which has the special PRP0001 device ID in its
   list of identifiers and a _DSD object with the <quote>compatible</quote> property, use
   that property to match against the given list of identifiers.
</para>
</refsect1>
</refentry>

<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.1.27</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>

<!-- 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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>struct uio_info * <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.1.27</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>struct device * <parameter>parent</parameter></paramdef>
   <paramdef>struct uio_info * <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.1.27</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>struct uio_info * <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.1.27</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.1.27</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.1.27</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.1.27</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>parport_claim</function>, and the return value is the same as for
   <function>parport_claim</function>.  If it fails, the port is left unclaimed and it is
   the driver's responsibility to reclaim the port.
   </para><para>

   The <function>parport_yield</function> and <function>parport_yield_blocking</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.1.27</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>parport_claim_or_block</function>, and the return value is the same as for
   <function>parport_claim_or_block</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.1.27</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.1.27</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>parport_set_timeout</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>parport_wait_event</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.1.27</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.1.27</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>parport_negotiate</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.1.27</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>parport_negotiate</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.1.27</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>parport_wait_peripheral</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>parport_wait_event</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.1.27</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>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     structure describing the driver
    </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>

   The <parameter>drv</parameter> structure is allocated by the caller and must not be
   deallocated until after calling <function>parport_unregister_driver</function>.
   </para><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>parport_get_port</function> to do so.  Calling
   <function>parport_register_device</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>parport_get_port</function> to do so.
   </para><para>

   Returns 0 on success.  Currently it always succeeds.
</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.1.27</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.1.27</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>parport_put_port</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.1.27</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>parport_get_port</function>,
   once the port is no longer needed.
</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.1.27</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>parport_register_port</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>parport_announce_port</function>.
   </para><para>

   The <parameter>ops</parameter> structure is allocated by the caller, and must not be
   deallocated before calling <function>parport_remove_port</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.1.27</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>parport_announce_port</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.1.27</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.1.27</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>parport_claim</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.1.27</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>parport_register_device</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.1.27</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>parport_get_port</function> done already; to throw
   away the reference to the port that <function>parport_find_number</function>
   gives you, use <function>parport_put_port</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.1.27</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>parport_get_port</function> done already; to throw
   away the reference to the port that <function>parport_find_base</function>
   gives you, use <function>parport_put_port</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.1.27</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>parport_claim</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.1.27</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>parport_claim</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.1.27</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.1.27</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>parport_register_device</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>parport_register_device</function>.  The return value is the same as
   for <function>parport_register_device</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_close</refname>
 <refpurpose>
     close a device opened with <function>parport_open</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>parport_open</function> as <function>parport_unregister_device</function> is to
   <function>parport_register_device</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>mpt_interrupt</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>mpt_register</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>printk</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.1.27</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>snd_printk</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.1.27</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.1.27</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.1.27</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.1.27</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>snd_printk</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.1.27</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>struct device * <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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>register_sound_mixer</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.1.27</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>register_sound_midi</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.1.27</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>register_sound_dsp</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.1.27</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.1.27</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>snd_pcm_stream_lock</function> but with the local
   IRQ (only when nonatomic is false).  In nonatomic case, this is identical
   as <function>snd_pcm_stream_lock</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>snd_pcm_group_for_each_entry</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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-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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>snd_pcm_lib_alloc_vmalloc_buffer</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>snd_pcm_new</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.1.27</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>snd_pcm_set_ops</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.1.27</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>snd_pcm_set_ops</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.1.27</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.1.27</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.1.27</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>snd_card_disconnect</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.1.27</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.1.27</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>snd_device_new</function>.  Usually this is called from <function>snd_card_register</function>,
   but it can be called later if any new devices are created after
   invocation of <function>snd_card_register</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-iprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_iprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_iprintf</refname>
 <refpurpose>
  printf on the procfs buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_iprintf </function></funcdef>
   <paramdef>struct snd_info_buffer * <parameter>buffer</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</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>fmt</parameter></term>
   <listitem>
    <para>
     the printf format
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Outputs the string on the procfs buffer just like <function>printf</function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The size of output string, or a negative error code.
</para>
</refsect1>
</refentry>

<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.1.27</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.1.27</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.1.27</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.1.27</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-card-proc-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_proc_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_proc_new</refname>
 <refpurpose>
     create an info entry for the given card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_proc_new </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct snd_info_entry ** <parameter>entryp</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>entryp</parameter></term>
   <listitem>
    <para>
     the pointer to store the new info entry
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new info entry and assigns it to the given card.
   Unlike <function>snd_info_create_card_entry</function>, this function registers the
   info entry as an ALSA device component, so that it can be
   unregistered/released without explicit call.
   Also, you don't have to register this entry via <function>snd_info_register</function>,
   since this will be registered by <function>snd_card_register</function> automatically.
   </para><para>

   The parent is assumed as card-&gt;proc_root.
   </para><para>

   For releasing this entry, use <function>snd_device_free</function> instead of
   <function>snd_info_free_entry</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-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.1.27</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.  Don't call this after registered.
</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.1.27</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.1.27</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.1.27</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.1.27</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>snd_rawmidi_transmit_peek</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.1.27</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>snd_rawmidi_transmit_ack</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.1.27</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>__snd_rawmidi_transmit_ack</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.1.27</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.1.27</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.1.27</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>snd_rawmidi_set_ops</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.1.27</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.1.27</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.1.27</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.1.27</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>struct device * <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.1.27</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>struct device * <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>snd_register_device</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.1.27</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.1.27</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.1.27</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.1.27</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>struct device * <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.1.27</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.1.27</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.1.27</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.1.27</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>snd_pcm_lib_malloc_pages</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.1.27</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>snd_pcm_lib_alloc_vmalloc_buffer</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.1.27</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>snd_pcm_lib_alloc_vmalloc_buffer</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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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.1.27</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>snd_card_free</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>snd_card_file_add</function> function.
   If all files are removed and <function>snd_card_free_when_closed</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>snd_ctl_new1</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.1.27</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>snd_ctl_new1</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.1.27</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.1.27</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>snd_ctl_free_one</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>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.1.27</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>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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>snd_pcm_stream_lock</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.1.27</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>snd_pcm_stream_lock</function> and disables the local
   IRQ (only when nonatomic is false).  In nonatomic case, this is identical
   as <function>snd_pcm_stream_lock</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.1.27</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>snd_pcm_stream_lock_irq</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.1.27</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>snd_pcm_stream_lock_irqsave</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.1.27</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.1.27</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>snd_pcm_stop</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>snd_malloc_pages</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.1.27</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>struct device * <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.1.27</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>struct device * <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.1.27</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>snd_dma_alloc_pages</function>.
</para>
</refsect1>
</refentry>

<!-- FIXME: Removed for now since no structured comments in source
X!Isound/sound_firmware.c
-->
  </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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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,&lt;addr&gt;,&lt;options&gt;
   console=&lt;name&gt;,io|mmio|mmio32,&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.1.27</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.1.27</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.1.27</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.1.27</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>uart_remove_one_port</function> if it registered them with <function>uart_add_one_port</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>input_open_device</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>input_close_device</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>input_event</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>input_open_device</function> and <function>input_close_device</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.1.27</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.1.27</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.1.27</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>struct input_dev * <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.1.27</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.1.27</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>struct input_dev * <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>input_inject_event</function>.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   <function>input_event</function> may be safely used right after input device was
   allocated with <function>input_allocate_device</function>, even before it is registered
   with <function>input_register_device</function>, but the event will not reach any of the
   input handlers. Such early invocation of <function>input_event</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.1.27</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>struct input_handle * <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>input_event</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.1.27</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>struct input_dev * <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.1.27</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>struct input_handle * <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.1.27</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>struct input_handle * <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.1.27</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>struct input_handle * <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.1.27</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>struct input_handle * <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.1.27</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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_allocate_device</refname>
 <refpurpose>
     allocate memory for new input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct input_dev * <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>input_free_device</function> to free devices that have not been
   registered; <function>input_unregister_device</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_input_allocate_device</refname>
 <refpurpose>
     allocate managed input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct input_dev * <function>devm_input_allocate_device </function></funcdef>
   <paramdef>struct device * <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.1.27</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>struct input_dev * <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>input_register_device</function>
   was not called yet or if it failed. Once device was registered
   use <function>input_unregister_device</function> and memory will be freed once last
   reference to the device is dropped.
   </para><para>

   Device should be allocated by <function>input_allocate_device</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.1.27</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>struct input_dev * <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-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.1.27</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>struct input_dev * <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>input_allocate_device</function> and all it's capabilities
   set up before registering.
   If function fails the device must be freed with <function>input_free_device</function>.
   Once device has been successfully registered it can be unregistered
   with <function>input_unregister_device</function>; <function>input_free_device</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>devm_input_allocate_device</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>input_event</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.1.27</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>struct input_dev * <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.1.27</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>struct input_handler * <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.1.27</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>struct input_handler * <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.1.27</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>struct input_handler * <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 usind in atonic
   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.1.27</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>struct input_handle * <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>input_open_device</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.1.27</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>struct input_handle * <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.1.27</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.1.27</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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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 ffect 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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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.1.27</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>input_mt_report_slot_state</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.1.27</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>input_mt_sync_frame</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.1.27</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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <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.1.27</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>struct input_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int * <parameter>slots</parameter></paramdef>
   <paramdef>const struct input_mt_pos * <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.1.27</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>struct input_dev * <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>input_mt_sync_frame</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.1.27</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_allocate_polled_device</refname>
 <refpurpose>
  allocate memory for polled device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct input_polled_dev * <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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_input_allocate_polled_device</refname>
 <refpurpose>
     allocate managed polled device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct input_polled_dev * <function>devm_input_allocate_polled_device </function></funcdef>
   <paramdef>struct device * <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>struct input_polled_dev</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>input_register_polled_device</function> function).
   </para><para>

   If you want to manually unregister and free such managed polled devices,
   it can be still done by calling <function>input_unregister_polled_device</function> and
   <function>input_free_polled_device</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.1.27</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>struct input_polled_dev * <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.1.27</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>struct input_polled_dev * <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>input_allocate_polled_device</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.1.27</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>struct input_polled_dev * <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>input_free_polled_device</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.1.27</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.1.27</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>matrix_keymap_data</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.1.27</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>struct device * <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.1.27</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sparse_keymap_entry_from_scancode</refname>
 <refpurpose>
  perform sparse keymap lookup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct key_entry * <function>sparse_keymap_entry_from_scancode </function></funcdef>
   <paramdef>struct input_dev * <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>struct key_entry</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sparse_keymap_entry_from_keycode</refname>
 <refpurpose>
     perform sparse keymap lookup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct key_entry * <function>sparse_keymap_entry_from_keycode </function></funcdef>
   <paramdef>struct input_dev * <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>struct key_entry</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.1.27</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>struct input_dev * <parameter>dev</parameter></paramdef>
   <paramdef>const struct key_entry * <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>key_entry</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>sparse_keymap_free</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.1.27</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>struct input_dev * <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>sparse_keymap_setup</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.1.27</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>struct input_dev * <parameter>dev</parameter></paramdef>
   <paramdef>const struct key_entry * <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>struct key_entry</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.1.27</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>struct input_dev * <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>struct spi_master</structname>.
	SPI devices are children of that master, represented as a
	<structname>struct spi_device</structname> and manufactured from
	<structname>struct spi_board_info</structname> descriptors which
	are usually provided by board-specific initialization code.
	A <structname>struct spi_driver</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>struct spi_message</structname>
	objects, which are processed and completed asynchronously.
	(There are synchronous wrappers, however.)  Messages are
	built from one or more <structname>struct spi_transfer</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-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.1.27</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;
};  </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>
  </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.1.27</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.1.27</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>struct spi_driver * <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.1.27</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.1.27</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 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>spi_finalize_current_message</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>spi_finalize_current_transfer</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>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.1.27</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.1.27</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.1.27</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>struct spi_message * <parameter>m</parameter></paramdef>
   <paramdef>struct spi_transfer * <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.1.27</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>struct spi_device * <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 writes the buffer and returns zero or a negative error code.
   Callable only from contexts that can sleep.
</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.1.27</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>struct spi_device * <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 reads the buffer and returns zero or a negative error code.
   Callable only from contexts that can sleep.
</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.1.27</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>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>struct spi_transfer * <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>spi_sync</function>.
   </para><para>

   It returns 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.1.27</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>struct spi_device * <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 returns the (unsigned) eight bit number returned by the
   device, or else a negative error code.  Callable only from
   contexts that can sleep.
</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.1.27</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>struct spi_device * <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 returns the (unsigned) sixteen bit number returned by the
   device, or else a negative error code.  Callable only from
   contexts that can sleep.
   </para><para>

   The number is returned in wire-order, which is at least sometimes
   big-endian.
</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.1.27</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>struct spi_device * <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 returns the (unsigned) sixteen bit number returned by the device in cpu
   endianness, or else a negative error code. Callable only from contexts that
   can sleep.
   </para><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>
</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.1.27</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>spi_new_device</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>spi_new_device</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.1.27</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>
</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.1.27</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 spi_driver * <parameter>sdrv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <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>
</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_alloc_device</refname>
 <refpurpose>
     Allocate a new SPI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct spi_device * <function>spi_alloc_device </function></funcdef>
   <paramdef>struct spi_master * <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>spi_add_device</function> on it.
   </para><para>

   Caller is responsible to call <function>spi_add_device</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><para>

   Returns 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.1.27</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>struct spi_device * <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><para>

   Returns 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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_new_device</refname>
 <refpurpose>
     instantiate one new SPI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct spi_device * <function>spi_new_device </function></funcdef>
   <paramdef>struct spi_master * <parameter>master</parameter></paramdef>
   <paramdef>struct spi_board_info * <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><para>

   Returns 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.1.27</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>struct spi_master * <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.1.27</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>struct spi_message * <function>spi_get_next_queued_message </function></funcdef>
   <paramdef>struct spi_master * <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>
</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.1.27</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>struct spi_master * <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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_alloc_master</refname>
 <refpurpose>
     allocate SPI master controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct spi_master * <function>spi_alloc_master </function></funcdef>
   <paramdef>struct device * <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>spi_register_master</function>.
   </para><para>

   This must be called from context that can sleep.  It returns the SPI
   master structure on success, else NULL.
   </para><para>

   The caller is responsible for assigning the bus number and initializing
   the master's methods before calling <function>spi_register_master</function>; and (after errors
   adding the device) calling <function>spi_master_put</function> to prevent a memory leak.
</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.1.27</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>struct spi_master * <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>spi_alloc_master</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>spi_register_master</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>spi_unregister_master</function>.
</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.1.27</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>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct spi_master * <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>spi_alloc_master</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>spi_register_master</function> which will
   automatically be unregister
</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.1.27</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>struct spi_master * <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.1.27</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>struct spi_master * <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>
</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.1.27</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>struct spi_device * <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>
</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.1.27</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>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>struct spi_message * <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>
</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.1.27</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>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>struct spi_message * <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>
</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.1.27</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>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>struct spi_message * <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><para>

   It returns 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.1.27</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>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>struct spi_message * <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><para>

   It returns 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.1.27</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>struct spi_master * <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><para>

   It returns zero on success, else a negative error code.
</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.1.27</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>struct spi_master * <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><para>

   It returns zero on success, else a negative error code.
</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.1.27</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>struct spi_device * <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>
</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>struct i2c_client</structname>.  Those devices will
	be bound to a <structname>struct i2c_driver</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.1.27</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.1.27</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.1.27</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>i2c_register_board_info</function>;
   bus numbers identify adapters that aren't yet available.  For add-on boards,
   <function>i2c_new_device</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>struct i2c_client * <function>i2c_verify_client </function></funcdef>
   <paramdef>struct device * <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.1.27</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.1.27</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_new_device</refname>
 <refpurpose>
     instantiate an i2c device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2c_client * <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>i2c_unregister_device</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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_unregister_device</refname>
 <refpurpose>
     reverse effect of <function>i2c_new_device</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2c_unregister_device </function></funcdef>
   <paramdef>struct i2c_client * <parameter>client</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     value returned from <function>i2c_new_device</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.1.27</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>struct i2c_client * <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>i2c_transfer</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>i2c_unregister_device</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.1.27</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>struct device * <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.1.27</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.1.27</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>i2c_register_board_info</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.1.27</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.1.27</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>struct i2c_driver * <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.1.27</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>struct i2c_client * <function>i2c_use_client </function></funcdef>
   <paramdef>struct i2c_client * <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.1.27</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>struct i2c_client * <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.1.27</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.1.27</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.1.27</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>const struct i2c_client * <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.1.27</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>const struct i2c_client * <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.1.27</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>const struct i2c_client * <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.1.27</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>const struct i2c_client * <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.1.27</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>const struct i2c_client * <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.1.27</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>const struct i2c_client * <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.1.27</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>const struct i2c_client * <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.1.27</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>const struct i2c_client * <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.1.27</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>const struct i2c_client * <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.1.27</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>const struct i2c_client * <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.1.27</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>

  </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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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.1.27</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>struct hsi_client * <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.1.27</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>struct hsi_client * <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.1.27</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>struct hsi_client * <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.1.27</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>struct hsi_client * <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.1.27</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>struct hsi_client * <parameter>cl</parameter></paramdef>
   <paramdef>struct hsi_msg * <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.1.27</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>struct hsi_client * <parameter>cl</parameter></paramdef>
   <paramdef>struct hsi_msg * <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.1.27</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>struct hsi_client * <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.1.27</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>struct hsi_client * <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.1.27</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>struct hsi_port * <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.1.27</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>struct hsi_controller * <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.1.27</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>struct hsi_controller * <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.1.27</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>struct hsi_client_driver * <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.1.27</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>struct hsi_controller * <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.1.27</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>struct hsi_controller * <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.1.27</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>struct hsi_msg * <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.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hsi_alloc_msg</refname>
 <refpurpose>
     Allocate an HSI message
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct hsi_msg * <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.1.27</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>struct hsi_client * <parameter>cl</parameter></paramdef>
   <paramdef>struct hsi_msg * <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.1.27</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>struct hsi_client * <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.1.27</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>struct hsi_client * <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.1.27</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>struct hsi_client * <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.1.27</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>struct hsi_client * <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.1.27</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>struct hsi_port * <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.1.27</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>struct hsi_client * <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>

</book>