xref: /linux-4.1.27/Documentation/DocBook/kernel-api.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="LinuxKernelAPI">
 <bookinfo>
  <title>The Linux Kernel API</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="adt">
     <title>Data Types</title>
     <sect1><title>Doubly Linked Lists</title>
<!-- include/linux/list.h -->
<refentry id="API-list-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_add</refname>
 <refpurpose>
  add a new entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_add </function></funcdef>
   <paramdef>struct list_head * <parameter>new</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     new entry to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     list head to add it after
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Insert a new entry after the specified head.
   This is good for implementing stacks.
</para>
</refsect1>
</refentry>

<refentry id="API-list-add-tail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_add_tail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_add_tail</refname>
 <refpurpose>
     add a new entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_add_tail </function></funcdef>
   <paramdef>struct list_head * <parameter>new</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     new entry to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     list head to add it before
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Insert a new entry before the specified head.
   This is useful for implementing queues.
</para>
</refsect1>
</refentry>

<refentry id="API---list-del-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__list_del_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__list_del_entry</refname>
 <refpurpose>
     deletes entry from list.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__list_del_entry </function></funcdef>
   <paramdef>struct list_head * <parameter>entry</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>entry</parameter></term>
   <listitem>
    <para>
     the element to delete from the list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   <function>list_empty</function> on entry does not return true after this, the entry is
   in an undefined state.
</para>
</refsect1>
</refentry>

<refentry id="API-list-replace">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_replace</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_replace</refname>
 <refpurpose>
     replace old entry by new one
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_replace </function></funcdef>
   <paramdef>struct list_head * <parameter>old</parameter></paramdef>
   <paramdef>struct list_head * <parameter>new</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     the element to be replaced
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     the new element to insert
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If <parameter>old</parameter> was empty, it will be overwritten.
</para>
</refsect1>
</refentry>

<refentry id="API-list-del-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_del_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_del_init</refname>
 <refpurpose>
     deletes entry from list and reinitialize it.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_del_init </function></funcdef>
   <paramdef>struct list_head * <parameter>entry</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>entry</parameter></term>
   <listitem>
    <para>
     the element to delete from the list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-move">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_move</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_move</refname>
 <refpurpose>
     delete from one list and add as another's head
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_move </function></funcdef>
   <paramdef>struct list_head * <parameter>list</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     the entry to move
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head that will precede our entry
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-move-tail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_move_tail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_move_tail</refname>
 <refpurpose>
     delete from one list and add as another's tail
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_move_tail </function></funcdef>
   <paramdef>struct list_head * <parameter>list</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     the entry to move
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head that will follow our entry
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-is-last">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_is_last</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_is_last</refname>
 <refpurpose>
     tests whether <parameter>list</parameter> is the last entry in list <parameter>head</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>list_is_last </function></funcdef>
   <paramdef>const struct list_head * <parameter>list</parameter></paramdef>
   <paramdef>const struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     the entry to test
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head of the list
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-empty">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_empty</refname>
 <refpurpose>
     tests whether a list is empty
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>list_empty </function></funcdef>
   <paramdef>const struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the list to test.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-empty-careful">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_empty_careful</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_empty_careful</refname>
 <refpurpose>
     tests whether a list is empty and not being modified
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>list_empty_careful </function></funcdef>
   <paramdef>const struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the list to test
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   tests whether a list is empty _and_ checks that no other CPU might be
   in the process of modifying either member (next or prev)
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   using <function>list_empty_careful</function> without synchronization
   can only be safe if the only activity that can happen
   to the list entry is <function>list_del_init</function>. Eg. it cannot be used
   if another CPU could re-<function>list_add</function> it.
</para>
</refsect1>
</refentry>

<refentry id="API-list-rotate-left">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_rotate_left</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_rotate_left</refname>
 <refpurpose>
     rotate the list to the left
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_rotate_left </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>
     the head of the list
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-is-singular">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_is_singular</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_is_singular</refname>
 <refpurpose>
     tests whether a list has just one entry.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>list_is_singular </function></funcdef>
   <paramdef>const struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the list to test.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-cut-position">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_cut_position</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_cut_position</refname>
 <refpurpose>
     cut a list into two
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_cut_position </function></funcdef>
   <paramdef>struct list_head * <parameter>list</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
   <paramdef>struct list_head * <parameter>entry</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     a new list to add all removed entries
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     a list with entries
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>entry</parameter></term>
   <listitem>
    <para>
     an entry within head, could be the head itself
     and if so we won't cut the list
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This helper moves the initial part of <parameter>head</parameter>, up to and
   including <parameter>entry</parameter>, from <parameter>head</parameter> to <parameter>list</parameter>. You should
   pass on <parameter>entry</parameter> an element you know is on <parameter>head</parameter>. <parameter>list</parameter>
   should be an empty list or a list you do not care about
   losing its data.
</para>
</refsect1>
</refentry>

<refentry id="API-list-splice">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_splice</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_splice</refname>
 <refpurpose>
     join two lists, this is designed for stacks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_splice </function></funcdef>
   <paramdef>const struct list_head * <parameter>list</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     the new list to add.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the place to add it in the first list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-splice-tail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_splice_tail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_splice_tail</refname>
 <refpurpose>
     join two lists, each list being a queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_splice_tail </function></funcdef>
   <paramdef>struct list_head * <parameter>list</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     the new list to add.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the place to add it in the first list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-splice-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_splice_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_splice_init</refname>
 <refpurpose>
     join two lists and reinitialise the emptied list.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_splice_init </function></funcdef>
   <paramdef>struct list_head * <parameter>list</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     the new list to add.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the place to add it in the first list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The list at <parameter>list</parameter> is reinitialised
</para>
</refsect1>
</refentry>

<refentry id="API-list-splice-tail-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_splice_tail_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_splice_tail_init</refname>
 <refpurpose>
     join two lists and reinitialise the emptied list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_splice_tail_init </function></funcdef>
   <paramdef>struct list_head * <parameter>list</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     the new list to add.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the place to add it in the first list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each of the lists is a queue.
   The list at <parameter>list</parameter> is reinitialised
</para>
</refsect1>
</refentry>

<refentry id="API-list-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_entry</refname>
 <refpurpose>
     get the struct for this entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_entry </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 <structname>struct list_head</structname> pointer.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the type of the struct this is embedded in.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-first-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_first_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_first_entry</refname>
 <refpurpose>
     get the first element from a list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_first_entry </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 list head to take the element from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the type of the struct this is embedded in.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note, that list is expected to be not empty.
</para>
</refsect1>
</refentry>

<refentry id="API-list-last-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_last_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_last_entry</refname>
 <refpurpose>
     get the last element from a list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_last_entry </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 list head to take the element from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the type of the struct this is embedded in.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note, that list is expected to be not empty.
</para>
</refsect1>
</refentry>

<refentry id="API-list-first-entry-or-null">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_first_entry_or_null</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_first_entry_or_null</refname>
 <refpurpose>
     get the first element from a list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_first_entry_or_null </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 list head to take the element from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the type of the struct this is embedded in.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that if the list is empty, it returns NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-list-next-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_next_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_next_entry</refname>
 <refpurpose>
     get the next element in list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_next_entry </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to cursor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-prev-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_prev_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_prev_entry</refname>
 <refpurpose>
     get the prev element in list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_prev_entry </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to cursor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-for-each">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each</refname>
 <refpurpose>
     iterate over a list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the <structname>struct list_head</structname> to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-for-each-prev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_prev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_prev</refname>
 <refpurpose>
     iterate over a list backwards
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_prev </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the <structname>struct list_head</structname> to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-for-each-safe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_safe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_safe</refname>
 <refpurpose>
     iterate over a list safe against removal of list entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_safe </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the <structname>struct list_head</structname> to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     another <structname>struct list_head</structname> to use as temporary storage
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-for-each-prev-safe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_prev_safe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_prev_safe</refname>
 <refpurpose>
     iterate over a list backwards safe against removal of list entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_prev_safe </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the <structname>struct list_head</structname> to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     another <structname>struct list_head</structname> to use as temporary storage
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-for-each-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry</refname>
 <refpurpose>
     iterate over list of given type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_entry </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-for-each-entry-reverse">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_reverse</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_reverse</refname>
 <refpurpose>
     iterate backwards over list of given type.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_entry_reverse </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-prepare-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_prepare_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_prepare_entry</refname>
 <refpurpose>
     prepare a pos entry for use in <function>list_for_each_entry_continue</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_prepare_entry </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a start point
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head of the list
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Prepares a pos entry for use as a start point in <function>list_for_each_entry_continue</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-list-for-each-entry-continue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_continue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_continue</refname>
 <refpurpose>
     continue iteration over list of given type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_entry_continue </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Continue to iterate over list of given type, continuing after
   the current position.
</para>
</refsect1>
</refentry>

<refentry id="API-list-for-each-entry-continue-reverse">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_continue_reverse</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_continue_reverse</refname>
 <refpurpose>
     iterate backwards from the given point
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_entry_continue_reverse </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Start to iterate over list of given type backwards, continuing after
   the current position.
</para>
</refsect1>
</refentry>

<refentry id="API-list-for-each-entry-from">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_from</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_from</refname>
 <refpurpose>
     iterate over list of given type from the current point
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_entry_from </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over list of given type, continuing from current position.
</para>
</refsect1>
</refentry>

<refentry id="API-list-for-each-entry-safe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_safe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_safe</refname>
 <refpurpose>
     iterate over list of given type safe against removal of list entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_entry_safe </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     another type * to use as temporary storage
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-list-for-each-entry-safe-continue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_safe_continue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_safe_continue</refname>
 <refpurpose>
     continue list iteration safe against removal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_entry_safe_continue </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     another type * to use as temporary storage
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over list of given type, continuing after current point,
   safe against removal of list entry.
</para>
</refsect1>
</refentry>

<refentry id="API-list-for-each-entry-safe-from">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_safe_from</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_safe_from</refname>
 <refpurpose>
     iterate over list from current point safe against removal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_entry_safe_from </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     another type * to use as temporary storage
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over list of given type from current point, safe against
   removal of list entry.
</para>
</refsect1>
</refentry>

<refentry id="API-list-for-each-entry-safe-reverse">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_safe_reverse</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_safe_reverse</refname>
 <refpurpose>
     iterate backwards over list safe against removal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_entry_safe_reverse </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     another type * to use as temporary storage
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate backwards over list of given type, safe against removal
   of list entry.
</para>
</refsect1>
</refentry>

<refentry id="API-list-safe-reset-next">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_safe_reset_next</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_safe_reset_next</refname>
 <refpurpose>
     reset a stale list_for_each_entry_safe loop
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_safe_reset_next </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the loop cursor used in the list_for_each_entry_safe loop
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     temporary storage used in list_for_each_entry_safe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the list_head within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   list_safe_reset_next is not safe to use in general if the list may be
   modified concurrently (eg. the lock is dropped in the loop body). An
   exception to this is if the cursor element (pos) is pinned in the list,
   and list_safe_reset_next is called after re-taking the lock and before
   completing the current iteration of the loop body.
</para>
</refsect1>
</refentry>

<refentry id="API-hlist-for-each-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_for_each_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hlist_for_each_entry</refname>
 <refpurpose>
     iterate over list of given type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>hlist_for_each_entry </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the hlist_node within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-hlist-for-each-entry-continue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_for_each_entry_continue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hlist_for_each_entry_continue</refname>
 <refpurpose>
     iterate over a hlist continuing after current point
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>hlist_for_each_entry_continue </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the hlist_node within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-hlist-for-each-entry-from">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_for_each_entry_from</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hlist_for_each_entry_from</refname>
 <refpurpose>
     iterate over a hlist continuing from current point
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>hlist_for_each_entry_from </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the hlist_node within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-hlist-for-each-entry-safe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_for_each_entry_safe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hlist_for_each_entry_safe</refname>
 <refpurpose>
     iterate over list of given type safe against removal of list entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>hlist_for_each_entry_safe </function></funcdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
   <paramdef> <parameter>head</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     another <structname>struct hlist_node</structname> to use as temporary storage
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the head for your list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>member</parameter></term>
   <listitem>
    <para>
     the name of the hlist_node within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="libc">
     <title>Basic C Library Functions</title>

     <para>
       When writing drivers, you cannot in general use routines which are
       from the C Library.  Some of the functions have been found generally
       useful and they are listed below.  The behaviour of these functions
       may vary slightly from those defined by ANSI, and these deviations
       are noted in the text.
     </para>

     <sect1><title>String Conversions</title>
<!-- lib/vsprintf.c -->
<refentry id="API-simple-strtoull">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>simple_strtoull</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>simple_strtoull</refname>
 <refpurpose>
  convert a string to an unsigned long long
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long long <function>simple_strtoull </function></funcdef>
   <paramdef>const char * <parameter>cp</parameter></paramdef>
   <paramdef>char ** <parameter>endp</parameter></paramdef>
   <paramdef>unsigned int <parameter>base</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cp</parameter></term>
   <listitem>
    <para>
     The start of the string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>endp</parameter></term>
   <listitem>
    <para>
     A pointer to the end of the parsed string will be placed here
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     The number base to use
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is obsolete. Please use kstrtoull instead.
</para>
</refsect1>
</refentry>

<refentry id="API-simple-strtoul">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>simple_strtoul</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>simple_strtoul</refname>
 <refpurpose>
     convert a string to an unsigned long
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>simple_strtoul </function></funcdef>
   <paramdef>const char * <parameter>cp</parameter></paramdef>
   <paramdef>char ** <parameter>endp</parameter></paramdef>
   <paramdef>unsigned int <parameter>base</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cp</parameter></term>
   <listitem>
    <para>
     The start of the string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>endp</parameter></term>
   <listitem>
    <para>
     A pointer to the end of the parsed string will be placed here
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     The number base to use
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is obsolete. Please use kstrtoul instead.
</para>
</refsect1>
</refentry>

<refentry id="API-simple-strtol">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>simple_strtol</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>simple_strtol</refname>
 <refpurpose>
     convert a string to a signed long
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>simple_strtol </function></funcdef>
   <paramdef>const char * <parameter>cp</parameter></paramdef>
   <paramdef>char ** <parameter>endp</parameter></paramdef>
   <paramdef>unsigned int <parameter>base</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cp</parameter></term>
   <listitem>
    <para>
     The start of the string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>endp</parameter></term>
   <listitem>
    <para>
     A pointer to the end of the parsed string will be placed here
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     The number base to use
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is obsolete. Please use kstrtol instead.
</para>
</refsect1>
</refentry>

<refentry id="API-simple-strtoll">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>simple_strtoll</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>simple_strtoll</refname>
 <refpurpose>
     convert a string to a signed long long
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long long <function>simple_strtoll </function></funcdef>
   <paramdef>const char * <parameter>cp</parameter></paramdef>
   <paramdef>char ** <parameter>endp</parameter></paramdef>
   <paramdef>unsigned int <parameter>base</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cp</parameter></term>
   <listitem>
    <para>
     The start of the string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>endp</parameter></term>
   <listitem>
    <para>
     A pointer to the end of the parsed string will be placed here
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     The number base to use
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is obsolete. Please use kstrtoll instead.
</para>
</refsect1>
</refentry>

<refentry id="API-vsnprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vsnprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vsnprintf</refname>
 <refpurpose>
     Format a string and place it in a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vsnprintf </function></funcdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>size</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>buf</parameter></term>
   <listitem>
    <para>
     The buffer to place the result into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The size of the buffer, including the trailing null space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The format string to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args</parameter></term>
   <listitem>
    <para>
     Arguments for the format string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function follows C99 vsnprintf, but has some extensions:
   <constant>pS</constant> output the name of a text symbol with offset
   <constant>ps</constant> output the name of a text symbol without offset
   <constant>pF</constant> output the name of a function pointer with its offset
   <constant>pf</constant> output the name of a function pointer without its offset
   <constant>pB</constant> output the name of a backtrace symbol with its offset
   <constant>pR</constant> output the address range in a struct resource with decoded flags
   <constant>pr</constant> output the address range in a struct resource with raw flags
   <constant>pb</constant> output the bitmap with field width as the number of bits
   <constant>pbl</constant> output the bitmap as range list with field width as the number of bits
   <constant>pM</constant> output a 6-byte MAC address with colons
   <constant>pMR</constant> output a 6-byte MAC address with colons in reversed order
   <constant>pMF</constant> output a 6-byte MAC address with dashes
   <constant>pm</constant> output a 6-byte MAC address without colons
   <constant>pmR</constant> output a 6-byte MAC address without colons in reversed order
   <constant>pI4</constant> print an IPv4 address without leading zeros
   <constant>pi4</constant> print an IPv4 address with leading zeros
   <constant>pI6</constant> print an IPv6 address with colons
   <constant>pi6</constant> print an IPv6 address without colons
   <constant>pI6c</constant> print an IPv6 address as specified by RFC 5952
   <constant>pIS</constant> depending on sa_family of 'struct sockaddr *' print IPv4/IPv6 address
   <constant>piS</constant> depending on sa_family of 'struct sockaddr *' print IPv4/IPv6 address
   <constant>pU</constant>[bBlL] print a UUID/GUID in big or little endian using lower or upper
   case.
   %*pE[achnops] print an escaped buffer
   %*ph[CDN] a variable-length hex string with a separator (supports up to 64
   bytes of the input)
   <constant>pC</constant> output the name (Common Clock Framework) or address (legacy clock
   framework) of a clock
   <constant>pCn</constant> output the name (Common Clock Framework) or address (legacy clock
   framework) of a clock
   <constant>pCr</constant> output the current rate of a clock
   <constant>n</constant> is ignored
   </para><para>

   ** Please update Documentation/printk-formats.txt when making changes **
   </para><para>

   The return value is the number of characters which would
   be generated for the given input, excluding the trailing
   '\0', as per ISO C99. If you want to have the exact
   number of characters written into <parameter>buf</parameter> as return value
   (not including the trailing '\0'), use <function>vscnprintf</function>. If the
   return is greater than or equal to <parameter>size</parameter>, the resulting
   string is truncated.
   </para><para>

   If you're not already dealing with a va_list consider using <function>snprintf</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-vscnprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vscnprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vscnprintf</refname>
 <refpurpose>
     Format a string and place it in a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vscnprintf </function></funcdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>size</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>buf</parameter></term>
   <listitem>
    <para>
     The buffer to place the result into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The size of the buffer, including the trailing null space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The format string to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args</parameter></term>
   <listitem>
    <para>
     Arguments for the format string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The return value is the number of characters which have been written into
   the <parameter>buf</parameter> not including the trailing '\0'. If <parameter>size</parameter> is == 0 the function
   returns 0.
   </para><para>

   If you're not already dealing with a va_list consider using <function>scnprintf</function>.
   </para><para>

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

<refentry id="API-snprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snprintf</refname>
 <refpurpose>
     Format a string and place it in a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snprintf </function></funcdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     The buffer to place the result into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The size of the buffer, including the trailing null space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The format string to use
     @...: Arguments for the format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The return value is the number of characters which would be
   generated for the given input, excluding the trailing null,
   as per ISO C99.  If the return is greater than or equal to
   <parameter>size</parameter>, the resulting string is truncated.
   </para><para>

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

<refentry id="API-scnprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>scnprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>scnprintf</refname>
 <refpurpose>
     Format a string and place it in a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>scnprintf </function></funcdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     The buffer to place the result into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The size of the buffer, including the trailing null space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The format string to use
     @...: Arguments for the format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The return value is the number of characters written into <parameter>buf</parameter> not including
   the trailing '\0'. If <parameter>size</parameter> is == 0 the function returns 0.
</para>
</refsect1>
</refentry>

<refentry id="API-vsprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vsprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vsprintf</refname>
 <refpurpose>
     Format a string and place it in a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vsprintf </function></funcdef>
   <paramdef>char * <parameter>buf</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>buf</parameter></term>
   <listitem>
    <para>
     The buffer to place the result into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The format string to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args</parameter></term>
   <listitem>
    <para>
     Arguments for the format string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The function returns the number of characters written
   into <parameter>buf</parameter>. Use <function>vsnprintf</function> or <function>vscnprintf</function> in order to avoid
   buffer overflows.
   </para><para>

   If you're not already dealing with a va_list consider using <function>sprintf</function>.
   </para><para>

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

<refentry id="API-sprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sprintf</refname>
 <refpurpose>
     Format a string and place it in a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sprintf </function></funcdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     The buffer to place the result into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The format string to use
     @...: Arguments for the format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The function returns the number of characters written
   into <parameter>buf</parameter>. Use <function>snprintf</function> or <function>scnprintf</function> in order to avoid
   buffer overflows.
   </para><para>

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

<refentry id="API-vbin-printf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vbin_printf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vbin_printf</refname>
 <refpurpose>
     Parse a format string and place args' binary value in a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vbin_printf </function></funcdef>
   <paramdef>u32 * <parameter>bin_buf</parameter></paramdef>
   <paramdef>size_t <parameter>size</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>bin_buf</parameter></term>
   <listitem>
    <para>
     The buffer to place args' binary value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The size of the buffer(by words(32bits), not characters)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The format string to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args</parameter></term>
   <listitem>
    <para>
     Arguments for the format string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The format follows C99 vsnprintf, except <constant>n</constant> is ignored, and its argument
   is skipped.
   </para><para>

   The return value is the number of words(32bits) which would be generated for
   the given input.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   If the return value is greater than <parameter>size</parameter>, the resulting bin_buf is NOT
   valid for <function>bstr_printf</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-bstr-printf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bstr_printf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bstr_printf</refname>
 <refpurpose>
     Format a string from binary arguments and place it in a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bstr_printf </function></funcdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef>const u32 * <parameter>bin_buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     The buffer to place the result into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The size of the buffer, including the trailing null space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The format string to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bin_buf</parameter></term>
   <listitem>
    <para>
     Binary arguments for the format string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function like C99 vsnprintf, but the difference is that vsnprintf gets
   arguments from stack, and bstr_printf gets arguments from <parameter>bin_buf</parameter> which is
   a binary buffer that generated by vbin_printf.
   </para><para>

   The format follows C99 vsnprintf, but has some extensions:
   see vsnprintf comment for details.
   </para><para>

   The return value is the number of characters which would
   be generated for the given input, excluding the trailing
   '\0', as per ISO C99. If you want to have the exact
   number of characters written into <parameter>buf</parameter> as return value
   (not including the trailing '\0'), use <function>vscnprintf</function>. If the
   return is greater than or equal to <parameter>size</parameter>, the resulting
   string is truncated.
</para>
</refsect1>
</refentry>

<refentry id="API-bprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bprintf</refname>
 <refpurpose>
     Parse a format string and place args' binary value in a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bprintf </function></funcdef>
   <paramdef>u32 * <parameter>bin_buf</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bin_buf</parameter></term>
   <listitem>
    <para>
     The buffer to place args' binary value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The size of the buffer(by words(32bits), not characters)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     The format string to use
     @...: Arguments for the format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The function returns the number of words(u32) written
   into <parameter>bin_buf</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-vsscanf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vsscanf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vsscanf</refname>
 <refpurpose>
     Unformat a buffer into a list of arguments
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vsscanf </function></funcdef>
   <paramdef>const char * <parameter>buf</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>buf</parameter></term>
   <listitem>
    <para>
     input buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format of buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args</parameter></term>
   <listitem>
    <para>
     arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-sscanf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sscanf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sscanf</refname>
 <refpurpose>
     Unformat a buffer into a list of arguments
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sscanf </function></funcdef>
   <paramdef>const char * <parameter>buf</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     input buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     formatting of buffer
     @...:	resulting arguments
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</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-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>

<!-- lib/kstrtox.c -->
<refentry id="API-kstrtoull">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kstrtoull</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kstrtoull</refname>
 <refpurpose>
  convert a string to an unsigned long long
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kstrtoull </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>unsigned int <parameter>base</parameter></paramdef>
   <paramdef>unsigned long 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-kstrtoll">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kstrtoll</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kstrtoll</refname>
 <refpurpose>
     convert a string to a long long
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kstrtoll </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>unsigned int <parameter>base</parameter></paramdef>
   <paramdef>long 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-kstrtouint">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kstrtouint</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kstrtouint</refname>
 <refpurpose>
     convert a string to an unsigned int
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kstrtouint </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>unsigned int <parameter>base</parameter></paramdef>
   <paramdef>unsigned int * <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-kstrtoint">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kstrtoint</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kstrtoint</refname>
 <refpurpose>
     convert a string to an int
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kstrtoint </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>unsigned int <parameter>base</parameter></paramdef>
   <paramdef>int * <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>

     </sect1>
     <sect1><title>String Manipulation</title>
<!-- All functions are exported at now
X!Ilib/string.c
 -->
<!-- lib/string.c -->
<refentry id="API-strncasecmp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strncasecmp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strncasecmp</refname>
 <refpurpose>
  Case insensitive, length-limited string comparison
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>strncasecmp </function></funcdef>
   <paramdef>const char * <parameter>s1</parameter></paramdef>
   <paramdef>const char * <parameter>s2</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s1</parameter></term>
   <listitem>
    <para>
     One string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>s2</parameter></term>
   <listitem>
    <para>
     The other string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     the maximum number of characters to compare
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strcpy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strcpy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strcpy</refname>
 <refpurpose>
     Copy a <constant>NUL</constant> terminated string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strcpy </function></funcdef>
   <paramdef>char * <parameter>dest</parameter></paramdef>
   <paramdef>const char * <parameter>src</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dest</parameter></term>
   <listitem>
    <para>
     Where to copy the string to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     Where to copy the string from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strncpy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strncpy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strncpy</refname>
 <refpurpose>
     Copy a length-limited, C-string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strncpy </function></funcdef>
   <paramdef>char * <parameter>dest</parameter></paramdef>
   <paramdef>const char * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dest</parameter></term>
   <listitem>
    <para>
     Where to copy the string to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     Where to copy the string from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     The maximum number of bytes to copy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The result is not <constant>NUL-terminated</constant> if the source exceeds
   <parameter>count</parameter> bytes.
   </para><para>

   In the case where the length of <parameter>src</parameter> is less than  that  of
   count, the remainder of <parameter>dest</parameter> will be padded with <constant>NUL</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API-strlcpy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strlcpy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strlcpy</refname>
 <refpurpose>
     Copy a C-string into a sized buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>strlcpy </function></funcdef>
   <paramdef>char * <parameter>dest</parameter></paramdef>
   <paramdef>const char * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dest</parameter></term>
   <listitem>
    <para>
     Where to copy the string to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     Where to copy the string from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of destination buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>BSD</title>
<para>
   the result is always a valid
   NUL-terminated string that fits in the buffer (unless,
   of course, the buffer size is zero). It does not pad
   out the result like <function>strncpy</function> does.
</para>
</refsect1>
</refentry>

<refentry id="API-strcat">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strcat</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strcat</refname>
 <refpurpose>
     Append one <constant>NUL-terminated</constant> string to another
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strcat </function></funcdef>
   <paramdef>char * <parameter>dest</parameter></paramdef>
   <paramdef>const char * <parameter>src</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dest</parameter></term>
   <listitem>
    <para>
     The string to be appended to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     The string to append to it
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strncat">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strncat</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strncat</refname>
 <refpurpose>
     Append a length-limited, C-string to another
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strncat </function></funcdef>
   <paramdef>char * <parameter>dest</parameter></paramdef>
   <paramdef>const char * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dest</parameter></term>
   <listitem>
    <para>
     The string to be appended to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     The string to append to it
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     The maximum numbers of bytes to copy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that in contrast to <function>strncpy</function>, <function>strncat</function> ensures the result is
   terminated.
</para>
</refsect1>
</refentry>

<refentry id="API-strlcat">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strlcat</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strlcat</refname>
 <refpurpose>
     Append a length-limited, C-string to another
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>strlcat </function></funcdef>
   <paramdef>char * <parameter>dest</parameter></paramdef>
   <paramdef>const char * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dest</parameter></term>
   <listitem>
    <para>
     The string to be appended to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     The string to append to it
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     The size of the destination buffer.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strcmp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strcmp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strcmp</refname>
 <refpurpose>
     Compare two strings
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>strcmp </function></funcdef>
   <paramdef>const char * <parameter>cs</parameter></paramdef>
   <paramdef>const char * <parameter>ct</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cs</parameter></term>
   <listitem>
    <para>
     One string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ct</parameter></term>
   <listitem>
    <para>
     Another string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strncmp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strncmp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strncmp</refname>
 <refpurpose>
     Compare two length-limited strings
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>strncmp </function></funcdef>
   <paramdef>const char * <parameter>cs</parameter></paramdef>
   <paramdef>const char * <parameter>ct</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cs</parameter></term>
   <listitem>
    <para>
     One string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ct</parameter></term>
   <listitem>
    <para>
     Another string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     The maximum number of bytes to compare
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strchr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strchr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strchr</refname>
 <refpurpose>
     Find the first occurrence of a character in a string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strchr </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>int <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The string to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The character to search for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strchrnul">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strchrnul</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strchrnul</refname>
 <refpurpose>
     Find and return a character in a string, or end of string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strchrnul </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>int <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The string to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The character to search for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns pointer to first occurrence of 'c' in s. If c is not found, then
   return a pointer to the null byte at the end of s.
</para>
</refsect1>
</refentry>

<refentry id="API-strrchr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strrchr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strrchr</refname>
 <refpurpose>
     Find the last occurrence of a character in a string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strrchr </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>int <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The string to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The character to search for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strnchr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strnchr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strnchr</refname>
 <refpurpose>
     Find a character in a length limited string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strnchr </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
   <paramdef>int <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The string to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     The number of characters to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The character to search for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-skip-spaces">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skip_spaces</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skip_spaces</refname>
 <refpurpose>
     Removes leading whitespace from <parameter>str</parameter>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>skip_spaces </function></funcdef>
   <paramdef>const char * <parameter>str</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>str</parameter></term>
   <listitem>
    <para>
     The string to be stripped.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a pointer to the first non-whitespace character in <parameter>str</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-strim">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strim</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strim</refname>
 <refpurpose>
     Removes leading and trailing whitespace from <parameter>s</parameter>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strim </function></funcdef>
   <paramdef>char * <parameter>s</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The string to be stripped.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that the first trailing whitespace is replaced with a <constant>NUL-terminator</constant>
   in the given string <parameter>s</parameter>. Returns a pointer to the first non-whitespace
   character in <parameter>s</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-strlen">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strlen</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strlen</refname>
 <refpurpose>
     Find the length of a string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>strlen </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The string to be sized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strnlen">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strnlen</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strnlen</refname>
 <refpurpose>
     Find the length of a length-limited string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>strnlen </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The string to be sized
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     The maximum number of bytes to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strspn">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strspn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strspn</refname>
 <refpurpose>
     Calculate the length of the initial substring of <parameter>s</parameter> which only contain letters in <parameter>accept</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>strspn </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>const char * <parameter>accept</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The string to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>accept</parameter></term>
   <listitem>
    <para>
     The string to search for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strcspn">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strcspn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strcspn</refname>
 <refpurpose>
     Calculate the length of the initial substring of <parameter>s</parameter> which does not contain letters in <parameter>reject</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>strcspn </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>const char * <parameter>reject</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The string to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reject</parameter></term>
   <listitem>
    <para>
     The string to avoid
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strpbrk">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strpbrk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strpbrk</refname>
 <refpurpose>
     Find the first occurrence of a set of characters
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strpbrk </function></funcdef>
   <paramdef>const char * <parameter>cs</parameter></paramdef>
   <paramdef>const char * <parameter>ct</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cs</parameter></term>
   <listitem>
    <para>
     The string to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ct</parameter></term>
   <listitem>
    <para>
     The characters to search for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strsep">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strsep</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strsep</refname>
 <refpurpose>
     Split a string into tokens
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strsep </function></funcdef>
   <paramdef>char ** <parameter>s</parameter></paramdef>
   <paramdef>const char * <parameter>ct</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The string to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ct</parameter></term>
   <listitem>
    <para>
     The characters to search for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>strsep</function> updates <parameter>s</parameter> to point after the token, ready for the next call.
   </para><para>

   It returns empty tokens, too, behaving exactly like the libc function
   of that name. In fact, it was stolen from glibc2 and de-fancy-fied.
   Same semantics, slimmer shape. ;)
</para>
</refsect1>
</refentry>

<refentry id="API-sysfs-streq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sysfs_streq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sysfs_streq</refname>
 <refpurpose>
     return true if strings are equal, modulo trailing newline
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>sysfs_streq </function></funcdef>
   <paramdef>const char * <parameter>s1</parameter></paramdef>
   <paramdef>const char * <parameter>s2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s1</parameter></term>
   <listitem>
    <para>
     one string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>s2</parameter></term>
   <listitem>
    <para>
     another string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine returns true iff two strings are equal, treating both
   NUL and newline-then-NUL as equivalent string terminations.  It's
   geared for use with sysfs input strings, which generally terminate
   with newlines but are compared against values without newlines.
</para>
</refsect1>
</refentry>

<refentry id="API-strtobool">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strtobool</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strtobool</refname>
 <refpurpose>
     convert common user inputs into boolean values
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>strtobool </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>bool * <parameter>res</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     input string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     result
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine returns 0 iff the first character is one of 'Yy1Nn0'.
   Otherwise it will return -EINVAL.  Value pointed to by res is
   updated upon finding a match.
</para>
</refsect1>
</refentry>

<refentry id="API-memset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>memset</refname>
 <refpurpose>
     Fill a region of memory with the given value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>memset </function></funcdef>
   <paramdef>void * <parameter>s</parameter></paramdef>
   <paramdef>int <parameter>c</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     Pointer to the start of the area.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The byte to fill the area with
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     The size of the area.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Do not use <function>memset</function> to access IO space, use <function>memset_io</function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-memzero-explicit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memzero_explicit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>memzero_explicit</refname>
 <refpurpose>
     Fill a region of memory (e.g. sensitive keying data) with 0s.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>memzero_explicit </function></funcdef>
   <paramdef>void * <parameter>s</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     Pointer to the start of the area.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     The size of the area.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   usually using <function>memset</function> is just fine (!), but in cases
   where clearing out _local_ data at the end of a scope is
   necessary, <function>memzero_explicit</function> should be used instead in
   order to prevent the compiler from optimising away zeroing.
   </para><para>

   <function>memzero_explicit</function> doesn't need an arch-specific version as
   it just invokes the one of <function>memset</function> implicitly.
</para>
</refsect1>
</refentry>

<refentry id="API-memcpy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memcpy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>memcpy</refname>
 <refpurpose>
     Copy one area of memory to another
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>memcpy </function></funcdef>
   <paramdef>void * <parameter>dest</parameter></paramdef>
   <paramdef>const void * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dest</parameter></term>
   <listitem>
    <para>
     Where to copy to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     Where to copy from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     The size of the area.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   You should not use this function to access IO space, use <function>memcpy_toio</function>
   or <function>memcpy_fromio</function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-memmove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memmove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>memmove</refname>
 <refpurpose>
     Copy one area of memory to another
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>memmove </function></funcdef>
   <paramdef>void * <parameter>dest</parameter></paramdef>
   <paramdef>const void * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dest</parameter></term>
   <listitem>
    <para>
     Where to copy to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     Where to copy from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     The size of the area.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unlike <function>memcpy</function>, <function>memmove</function> copes with overlapping areas.
</para>
</refsect1>
</refentry>

<refentry id="API-memcmp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memcmp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>memcmp</refname>
 <refpurpose>
     Compare two areas of memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__visible int <function>memcmp </function></funcdef>
   <paramdef>const void * <parameter>cs</parameter></paramdef>
   <paramdef>const void * <parameter>ct</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cs</parameter></term>
   <listitem>
    <para>
     One area of memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ct</parameter></term>
   <listitem>
    <para>
     Another area of memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     The size of the area.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-memscan">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memscan</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>memscan</refname>
 <refpurpose>
     Find a character in an area of memory.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>memscan </function></funcdef>
   <paramdef>void * <parameter>addr</parameter></paramdef>
   <paramdef>int <parameter>c</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     The memory area
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The byte to search for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The size of the area.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   returns the address of the first occurrence of <parameter>c</parameter>, or 1 byte past
   the area if <parameter>c</parameter> is not found
</para>
</refsect1>
</refentry>

<refentry id="API-strstr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strstr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strstr</refname>
 <refpurpose>
     Find the first substring in a <constant>NUL</constant> terminated string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strstr </function></funcdef>
   <paramdef>const char * <parameter>s1</parameter></paramdef>
   <paramdef>const char * <parameter>s2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s1</parameter></term>
   <listitem>
    <para>
     The string to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>s2</parameter></term>
   <listitem>
    <para>
     The string to search for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-strnstr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strnstr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strnstr</refname>
 <refpurpose>
     Find the first substring in a length-limited string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strnstr </function></funcdef>
   <paramdef>const char * <parameter>s1</parameter></paramdef>
   <paramdef>const char * <parameter>s2</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s1</parameter></term>
   <listitem>
    <para>
     The string to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>s2</parameter></term>
   <listitem>
    <para>
     The string to search for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     the maximum number of characters to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-memchr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memchr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>memchr</refname>
 <refpurpose>
     Find a character in an area of memory.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>memchr </function></funcdef>
   <paramdef>const void * <parameter>s</parameter></paramdef>
   <paramdef>int <parameter>c</parameter></paramdef>
   <paramdef>size_t <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The memory area
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The byte to search for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     The size of the area.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   returns the address of the first occurrence of <parameter>c</parameter>, or <constant>NULL</constant>
   if <parameter>c</parameter> is not found
</para>
</refsect1>
</refentry>

<refentry id="API-memchr-inv">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memchr_inv</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>memchr_inv</refname>
 <refpurpose>
     Find an unmatching character in an area of memory.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>memchr_inv </function></funcdef>
   <paramdef>const void * <parameter>start</parameter></paramdef>
   <paramdef>int <parameter>c</parameter></paramdef>
   <paramdef>size_t <parameter>bytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     The memory area
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     Find a character other than c
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bytes</parameter></term>
   <listitem>
    <para>
     The size of the area.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   returns the address of the first character other than <parameter>c</parameter>, or <constant>NULL</constant>
   if the whole buffer contains just <parameter>c</parameter>.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Bit Operations</title>
<!-- arch/x86/include/asm/bitops.h -->
<refentry id="API-set-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>set_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>set_bit</refname>
 <refpurpose>
  Atomically set a bit in memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>set_bit </function></funcdef>
   <paramdef>long <parameter>nr</parameter></paramdef>
   <paramdef>volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     the bit to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     the address to start counting from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is atomic and may not be reordered.  See <function>__set_bit</function>
   if you do not require the atomic guarantees.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   there are no guarantees that this function will not be reordered
   on non x86 architectures, so if you are writing portable code,
   make sure not to rely on its reordering guarantees.
   </para><para>

   Note that <parameter>nr</parameter> may be almost arbitrarily large; this function is not
   restricted to acting on a single-word quantity.
</para>
</refsect1>
</refentry>

<refentry id="API---set-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__set_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__set_bit</refname>
 <refpurpose>
     Set a bit in memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__set_bit </function></funcdef>
   <paramdef>long <parameter>nr</parameter></paramdef>
   <paramdef>volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     the bit to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     the address to start counting from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unlike <function>set_bit</function>, this function is non-atomic and may be reordered.
   If it's called on the same region of memory simultaneously, the effect
   may be that only one operation succeeds.
</para>
</refsect1>
</refentry>

<refentry id="API-clear-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clear_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clear_bit</refname>
 <refpurpose>
     Clears a bit in memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>clear_bit </function></funcdef>
   <paramdef>long <parameter>nr</parameter></paramdef>
   <paramdef>volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     Bit to clear
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Address to start counting from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>clear_bit</function> is atomic and may not be reordered.  However, it does
   not contain a memory barrier, so if it is used for locking purposes,
   you should call <function>smp_mb__before_atomic</function> and/or <function>smp_mb__after_atomic</function>
   in order to ensure changes are visible on other processors.
</para>
</refsect1>
</refentry>

<refentry id="API---change-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__change_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__change_bit</refname>
 <refpurpose>
     Toggle a bit in memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__change_bit </function></funcdef>
   <paramdef>long <parameter>nr</parameter></paramdef>
   <paramdef>volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     the bit to change
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     the address to start counting from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unlike <function>change_bit</function>, this function is non-atomic and may be reordered.
   If it's called on the same region of memory simultaneously, the effect
   may be that only one operation succeeds.
</para>
</refsect1>
</refentry>

<refentry id="API-change-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>change_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>change_bit</refname>
 <refpurpose>
     Toggle a bit in memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>change_bit </function></funcdef>
   <paramdef>long <parameter>nr</parameter></paramdef>
   <paramdef>volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     Bit to change
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Address to start counting from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>change_bit</function> is atomic and may not be reordered.
   Note that <parameter>nr</parameter> may be almost arbitrarily large; this function is not
   restricted to acting on a single-word quantity.
</para>
</refsect1>
</refentry>

<refentry id="API-test-and-set-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>test_and_set_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>test_and_set_bit</refname>
 <refpurpose>
     Set a bit and return its old value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>test_and_set_bit </function></funcdef>
   <paramdef>long <parameter>nr</parameter></paramdef>
   <paramdef>volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     Bit to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Address to count from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This operation is atomic and cannot be reordered.
   It also implies a memory barrier.
</para>
</refsect1>
</refentry>

<refentry id="API-test-and-set-bit-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>test_and_set_bit_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>test_and_set_bit_lock</refname>
 <refpurpose>
     Set a bit and return its old value for lock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>test_and_set_bit_lock </function></funcdef>
   <paramdef>long <parameter>nr</parameter></paramdef>
   <paramdef>volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     Bit to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Address to count from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the same as test_and_set_bit on x86.
</para>
</refsect1>
</refentry>

<refentry id="API---test-and-set-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__test_and_set_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__test_and_set_bit</refname>
 <refpurpose>
     Set a bit and return its old value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__test_and_set_bit </function></funcdef>
   <paramdef>long <parameter>nr</parameter></paramdef>
   <paramdef>volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     Bit to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Address to count from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This operation is non-atomic and can be reordered.
   If two examples of this operation race, one can appear to succeed
   but actually fail.  You must protect multiple accesses with a lock.
</para>
</refsect1>
</refentry>

<refentry id="API-test-and-clear-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>test_and_clear_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>test_and_clear_bit</refname>
 <refpurpose>
     Clear a bit and return its old value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>test_and_clear_bit </function></funcdef>
   <paramdef>long <parameter>nr</parameter></paramdef>
   <paramdef>volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     Bit to clear
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Address to count from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This operation is atomic and cannot be reordered.
   It also implies a memory barrier.
</para>
</refsect1>
</refentry>

<refentry id="API---test-and-clear-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__test_and_clear_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__test_and_clear_bit</refname>
 <refpurpose>
     Clear a bit and return its old value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__test_and_clear_bit </function></funcdef>
   <paramdef>long <parameter>nr</parameter></paramdef>
   <paramdef>volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     Bit to clear
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Address to count from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This operation is non-atomic and can be reordered.
   If two examples of this operation race, one can appear to succeed
   but actually fail.  You must protect multiple accesses with a lock.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the operation is performed atomically with respect to
   the local CPU, but not other CPUs. Portable code should not
   rely on this behaviour.
   KVM relies on this behaviour on x86 for modifying memory that is also
</para>
</refsect1>
<refsect1>
<title>accessed from a hypervisor on the same CPU if running in a VM</title>
<para>
   don't change
   this without also updating arch/x86/kernel/kvm.c
</para>
</refsect1>
</refentry>

<refentry id="API-test-and-change-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>test_and_change_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>test_and_change_bit</refname>
 <refpurpose>
     Change a bit and return its old value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>test_and_change_bit </function></funcdef>
   <paramdef>long <parameter>nr</parameter></paramdef>
   <paramdef>volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     Bit to change
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Address to count from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This operation is atomic and cannot be reordered.
   It also implies a memory barrier.
</para>
</refsect1>
</refentry>

<refentry id="API-test-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>test_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>test_bit</refname>
 <refpurpose>
     Determine whether a bit is set
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>test_bit </function></funcdef>
   <paramdef>int <parameter>nr</parameter></paramdef>
   <paramdef>const volatile unsigned long * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     bit number to test
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Address to start counting from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---ffs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__ffs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__ffs</refname>
 <refpurpose>
     find first set bit in word
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>__ffs </function></funcdef>
   <paramdef>unsigned long <parameter>word</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>word</parameter></term>
   <listitem>
    <para>
     The word to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Undefined if no bit exists, so code should check against 0 first.
</para>
</refsect1>
</refentry>

<refentry id="API-ffz">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ffz</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ffz</refname>
 <refpurpose>
     find first zero bit in word
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>ffz </function></funcdef>
   <paramdef>unsigned long <parameter>word</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>word</parameter></term>
   <listitem>
    <para>
     The word to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Undefined if no zero exists, so code should check against ~0UL first.
</para>
</refsect1>
</refentry>

<refentry id="API-ffs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ffs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ffs</refname>
 <refpurpose>
     find first set bit in word
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ffs </function></funcdef>
   <paramdef>int <parameter>x</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     the word to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is defined the same way as the libc and compiler builtin ffs
   routines, therefore differs in spirit from the other bitops.
   </para><para>

   ffs(value) returns 0 if value is 0 or the position of the first
   set bit if value is nonzero. The first (least significant) bit
   is at position 1.
</para>
</refsect1>
</refentry>

<refentry id="API-fls">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fls</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fls</refname>
 <refpurpose>
     find last set bit in word
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fls </function></funcdef>
   <paramdef>int <parameter>x</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     the word to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is defined in a similar way as the libc and compiler builtin
   ffs, but returns the position of the most significant set bit.
   </para><para>

   fls(value) returns 0 if value is 0 or the position of the last
   set bit if value is nonzero. The last (most significant) bit is
   at position 32.
</para>
</refsect1>
</refentry>

<refentry id="API-fls64">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fls64</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fls64</refname>
 <refpurpose>
     find last set bit in a 64-bit word
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fls64 </function></funcdef>
   <paramdef>__u64 <parameter>x</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     the word to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is defined in a similar way as the libc and compiler builtin
   ffsll, but returns the position of the most significant set bit.
   </para><para>

   fls64(value) returns 0 if value is 0 or the position of the last
   set bit if value is nonzero. The last (most significant) bit is
   at position 64.
</para>
</refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="kernel-lib">
     <title>Basic Kernel Library Functions</title>

     <para>
       The Linux kernel provides more basic utility functions.
     </para>

     <sect1><title>Bitmap Operations</title>
<!-- lib/bitmap.c -->
<refentry id="API---bitmap-shift-right">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__bitmap_shift_right</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__bitmap_shift_right</refname>
 <refpurpose>
  logical right shift of the bits in a bitmap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__bitmap_shift_right </function></funcdef>
   <paramdef>unsigned long * <parameter>dst</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>src</parameter></paramdef>
   <paramdef>unsigned <parameter>shift</parameter></paramdef>
   <paramdef>unsigned <parameter>nbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     destination bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     source bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>shift</parameter></term>
   <listitem>
    <para>
     shift by this many bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nbits</parameter></term>
   <listitem>
    <para>
     bitmap size, in bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Shifting right (dividing) means moving bits in the MS -&gt; LS bit
   direction.  Zeros are fed into the vacated MS positions and the
   LS bits shifted off the bottom are lost.
</para>
</refsect1>
</refentry>

<refentry id="API---bitmap-shift-left">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__bitmap_shift_left</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__bitmap_shift_left</refname>
 <refpurpose>
     logical left shift of the bits in a bitmap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__bitmap_shift_left </function></funcdef>
   <paramdef>unsigned long * <parameter>dst</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>src</parameter></paramdef>
   <paramdef>unsigned int <parameter>shift</parameter></paramdef>
   <paramdef>unsigned int <parameter>nbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     destination bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     source bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>shift</parameter></term>
   <listitem>
    <para>
     shift by this many bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nbits</parameter></term>
   <listitem>
    <para>
     bitmap size, in bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Shifting left (multiplying) means moving bits in the LS -&gt; MS
   direction.  Zeros are fed into the vacated LS bit positions
   and those MS bits shifted off the top are lost.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-find-next-zero-area-off">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_find_next_zero_area_off</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_find_next_zero_area_off</refname>
 <refpurpose>
     find a contiguous aligned zero area
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>bitmap_find_next_zero_area_off </function></funcdef>
   <paramdef>unsigned long * <parameter>map</parameter></paramdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
   <paramdef>unsigned long <parameter>start</parameter></paramdef>
   <paramdef>unsigned int <parameter>nr</parameter></paramdef>
   <paramdef>unsigned long <parameter>align_mask</parameter></paramdef>
   <paramdef>unsigned long <parameter>align_offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>map</parameter></term>
   <listitem>
    <para>
     The address to base the search on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The bitmap size in bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     The bitnumber to start searching at
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     The number of zeroed bits we're looking for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>align_mask</parameter></term>
   <listitem>
    <para>
     Alignment mask for zero area
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>align_offset</parameter></term>
   <listitem>
    <para>
     Alignment offset for zero area.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The <parameter>align_mask</parameter> should be one less than a power of 2; the effect is that
   the bit offset of all zero areas this function finds plus <parameter>align_offset</parameter>
   is multiple of that power of 2.
</para>
</refsect1>
</refentry>

<refentry id="API---bitmap-parse">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__bitmap_parse</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__bitmap_parse</refname>
 <refpurpose>
     convert an ASCII hex string into a bitmap.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__bitmap_parse </function></funcdef>
   <paramdef>const char * <parameter>buf</parameter></paramdef>
   <paramdef>unsigned int <parameter>buflen</parameter></paramdef>
   <paramdef>int <parameter>is_user</parameter></paramdef>
   <paramdef>unsigned long * <parameter>maskp</parameter></paramdef>
   <paramdef>int <parameter>nmaskbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     pointer to buffer containing string.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buflen</parameter></term>
   <listitem>
    <para>
     buffer size in bytes.  If string is smaller than this
     then it must be terminated with a \0.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>is_user</parameter></term>
   <listitem>
    <para>
     location of buffer, 0 indicates kernel space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maskp</parameter></term>
   <listitem>
    <para>
     pointer to bitmap array that will contain result.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nmaskbits</parameter></term>
   <listitem>
    <para>
     size of bitmap, in bits.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Commas group hex digits into chunks.  Each chunk defines exactly 32
   bits of the resultant bitmask.  No chunk may specify a value larger
   than 32 bits (<constant>-EOVERFLOW</constant>), and if a chunk specifies a smaller value
   then leading 0-bits are prepended.  <constant>-EINVAL</constant> is returned for illegal
   characters and for grouping errors such as <quote>1,,5</quote>, <quote>,44</quote>, <quote>,</quote> and "".
   Leading and trailing whitespace accepted, but not embedded whitespace.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-parse-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_parse_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_parse_user</refname>
 <refpurpose>
     convert an ASCII hex string in a user buffer into a bitmap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bitmap_parse_user </function></funcdef>
   <paramdef>const char __user * <parameter>ubuf</parameter></paramdef>
   <paramdef>unsigned int <parameter>ulen</parameter></paramdef>
   <paramdef>unsigned long * <parameter>maskp</parameter></paramdef>
   <paramdef>int <parameter>nmaskbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ubuf</parameter></term>
   <listitem>
    <para>
     pointer to user buffer containing string.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ulen</parameter></term>
   <listitem>
    <para>
     buffer size in bytes.  If string is smaller than this
     then it must be terminated with a \0.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maskp</parameter></term>
   <listitem>
    <para>
     pointer to bitmap array that will contain result.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nmaskbits</parameter></term>
   <listitem>
    <para>
     size of bitmap, in bits.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Wrapper for <function>__bitmap_parse</function>, providing it with user buffer.
   </para><para>

   We cannot have this as an inline function in bitmap.h because it needs
   linux/uaccess.h to get the <function>access_ok</function> declaration and this causes
   cyclic dependencies.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-print-to-pagebuf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_print_to_pagebuf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_print_to_pagebuf</refname>
 <refpurpose>
     convert bitmap to list or hex format ASCII string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bitmap_print_to_pagebuf </function></funcdef>
   <paramdef>bool <parameter>list</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>maskp</parameter></paramdef>
   <paramdef>int <parameter>nmaskbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     indicates whether the bitmap must be list
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     page aligned buffer into which string is placed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maskp</parameter></term>
   <listitem>
    <para>
     pointer to bitmap to convert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nmaskbits</parameter></term>
   <listitem>
    <para>
     size of bitmap, in bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Output format is a comma-separated list of decimal numbers and
   ranges if list is specified or hex digits grouped into comma-separated
   sets of 8 digits/set. Returns the number of characters written to buf.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-parselist-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_parselist_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_parselist_user</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bitmap_parselist_user </function></funcdef>
   <paramdef>const char __user * <parameter>ubuf</parameter></paramdef>
   <paramdef>unsigned int <parameter>ulen</parameter></paramdef>
   <paramdef>unsigned long * <parameter>maskp</parameter></paramdef>
   <paramdef>int <parameter>nmaskbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ubuf</parameter></term>
   <listitem>
    <para>
     pointer to user buffer containing string.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ulen</parameter></term>
   <listitem>
    <para>
     buffer size in bytes.  If string is smaller than this
     then it must be terminated with a \0.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maskp</parameter></term>
   <listitem>
    <para>
     pointer to bitmap array that will contain result.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nmaskbits</parameter></term>
   <listitem>
    <para>
     size of bitmap, in bits.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Wrapper for <function>bitmap_parselist</function>, providing it with user buffer.
   </para><para>

   We cannot have this as an inline function in bitmap.h because it needs
   linux/uaccess.h to get the <function>access_ok</function> declaration and this causes
   cyclic dependencies.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-remap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_remap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_remap</refname>
 <refpurpose>
     Apply map defined by a pair of bitmaps to another bitmap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>bitmap_remap </function></funcdef>
   <paramdef>unsigned long * <parameter>dst</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>src</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>old</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>new</parameter></paramdef>
   <paramdef>unsigned int <parameter>nbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     remapped result
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     subset to be remapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     defines domain of map
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     defines range of map
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nbits</parameter></term>
   <listitem>
    <para>
     number of bits in each of these bitmaps
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Let <parameter>old</parameter> and <parameter>new</parameter> define a mapping of bit positions, such that
   whatever position is held by the n-th set bit in <parameter>old</parameter> is mapped
   to the n-th set bit in <parameter>new</parameter>.  In the more general case, allowing
   for the possibility that the weight 'w' of <parameter>new</parameter> is less than the
   weight of <parameter>old</parameter>, map the position of the n-th set bit in <parameter>old</parameter> to
   the position of the m-th set bit in <parameter>new</parameter>, where m == n % w.
   </para><para>

   If either of the <parameter>old</parameter> and <parameter>new</parameter> bitmaps are empty, or if <parameter>src</parameter> and
   <parameter>dst</parameter> point to the same location, then this routine copies <parameter>src</parameter>
   to <parameter>dst</parameter>.
   </para><para>

   The positions of unset bits in <parameter>old</parameter> are mapped to themselves
   (the identify map).
   </para><para>

   Apply the above specified mapping to <parameter>src</parameter>, placing the result in
   <parameter>dst</parameter>, clearing any bits previously set in <parameter>dst</parameter>.
   </para><para>

   For example, lets say that <parameter>old</parameter> has bits 4 through 7 set, and
   <parameter>new</parameter> has bits 12 through 15 set.  This defines the mapping of bit
   position 4 to 12, 5 to 13, 6 to 14 and 7 to 15, and of all other
   bit positions unchanged.  So if say <parameter>src</parameter> comes into this routine
   with bits 1, 5 and 7 set, then <parameter>dst</parameter> should leave with bits 1,
   13 and 15 set.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-bitremap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_bitremap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_bitremap</refname>
 <refpurpose>
     Apply map defined by a pair of bitmaps to a single bit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bitmap_bitremap </function></funcdef>
   <paramdef>int <parameter>oldbit</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>old</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>new</parameter></paramdef>
   <paramdef>int <parameter>bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>oldbit</parameter></term>
   <listitem>
    <para>
     bit position to be mapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     defines domain of map
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     defines range of map
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bits</parameter></term>
   <listitem>
    <para>
     number of bits in each of these bitmaps
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Let <parameter>old</parameter> and <parameter>new</parameter> define a mapping of bit positions, such that
   whatever position is held by the n-th set bit in <parameter>old</parameter> is mapped
   to the n-th set bit in <parameter>new</parameter>.  In the more general case, allowing
   for the possibility that the weight 'w' of <parameter>new</parameter> is less than the
   weight of <parameter>old</parameter>, map the position of the n-th set bit in <parameter>old</parameter> to
   the position of the m-th set bit in <parameter>new</parameter>, where m == n % w.
   </para><para>

   The positions of unset bits in <parameter>old</parameter> are mapped to themselves
   (the identify map).
   </para><para>

   Apply the above specified mapping to bit position <parameter>oldbit</parameter>, returning
   the new bit position.
   </para><para>

   For example, lets say that <parameter>old</parameter> has bits 4 through 7 set, and
   <parameter>new</parameter> has bits 12 through 15 set.  This defines the mapping of bit
   position 4 to 12, 5 to 13, 6 to 14 and 7 to 15, and of all other
   bit positions unchanged.  So if say <parameter>oldbit</parameter> is 5, then this routine
   returns 13.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-onto">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_onto</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_onto</refname>
 <refpurpose>
     translate one bitmap relative to another
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>bitmap_onto </function></funcdef>
   <paramdef>unsigned long * <parameter>dst</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>orig</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>relmap</parameter></paramdef>
   <paramdef>unsigned int <parameter>bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     resulting translated bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>orig</parameter></term>
   <listitem>
    <para>
     original untranslated bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>relmap</parameter></term>
   <listitem>
    <para>
     bitmap relative to which translated
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bits</parameter></term>
   <listitem>
    <para>
     number of bits in each of these bitmaps
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set the n-th bit of <parameter>dst</parameter> iff there exists some m such that the
   n-th bit of <parameter>relmap</parameter> is set, the m-th bit of <parameter>orig</parameter> is set, and
   the n-th bit of <parameter>relmap</parameter> is also the m-th _set_ bit of <parameter>relmap</parameter>.
   (If you understood the previous sentence the first time your
   read it, you're overqualified for your current job.)
   </para><para>

   In other words, <parameter>orig</parameter> is mapped onto (surjectively) <parameter>dst</parameter>,
   using the map { &lt;n, m&gt; | the n-th bit of <parameter>relmap</parameter> is the
   m-th set bit of <parameter>relmap</parameter> }.
   </para><para>

   Any set bits in <parameter>orig</parameter> above bit number W, where W is the
   weight of (number of set bits in) <parameter>relmap</parameter> are mapped nowhere.
   In particular, if for all bits m set in <parameter>orig</parameter>, m &gt;= W, then
   <parameter>dst</parameter> will end up empty.  In situations where the possibility
   of such an empty result is not desired, one way to avoid it is
   to use the <function>bitmap_fold</function> operator, below, to first fold the
   <parameter>orig</parameter> bitmap over itself so that all its set bits x are in the
   range 0 &lt;= x &lt; W.  The <function>bitmap_fold</function> operator does this by
   setting the bit (m % W) in <parameter>dst</parameter>, for each bit (m) set in <parameter>orig</parameter>.
   </para><para>

   Example [1] for <function>bitmap_onto</function>:
   Let's say <parameter>relmap</parameter> has bits 30-39 set, and <parameter>orig</parameter> has bits
   1, 3, 5, 7, 9 and 11 set.  Then on return from this routine,
   <parameter>dst</parameter> will have bits 31, 33, 35, 37 and 39 set.
   </para><para>

   When bit 0 is set in <parameter>orig</parameter>, it means turn on the bit in
   <parameter>dst</parameter> corresponding to whatever is the first bit (if any)
   that is turned on in <parameter>relmap</parameter>.  Since bit 0 was off in the
   above example, we leave off that bit (bit 30) in <parameter>dst</parameter>.
   </para><para>

   When bit 1 is set in <parameter>orig</parameter> (as in the above example), it
   means turn on the bit in <parameter>dst</parameter> corresponding to whatever
   is the second bit that is turned on in <parameter>relmap</parameter>.  The second
   bit in <parameter>relmap</parameter> that was turned on in the above example was
   bit 31, so we turned on bit 31 in <parameter>dst</parameter>.
   </para><para>

   Similarly, we turned on bits 33, 35, 37 and 39 in <parameter>dst</parameter>,
   because they were the 4th, 6th, 8th and 10th set bits
   set in <parameter>relmap</parameter>, and the 4th, 6th, 8th and 10th bits of
   <parameter>orig</parameter> (i.e. bits 3, 5, 7 and 9) were also set.
   </para><para>

   When bit 11 is set in <parameter>orig</parameter>, it means turn on the bit in
   <parameter>dst</parameter> corresponding to whatever is the twelfth bit that is
   turned on in <parameter>relmap</parameter>.  In the above example, there were
   only ten bits turned on in <parameter>relmap</parameter> (30..39), so that bit
   11 was set in <parameter>orig</parameter> had no affect on <parameter>dst</parameter>.
   </para><para>

   Example [2] for <function>bitmap_fold</function> + <function>bitmap_onto</function>:
   Let's say <parameter>relmap</parameter> has these ten bits set:
   40 41 42 43 45 48 53 61 74 95
   (for the curious, that's 40 plus the first ten terms of the
   Fibonacci sequence.)
   </para><para>

   Further lets say we use the following code, invoking
   <function>bitmap_fold</function> then bitmap_onto, as suggested above to
   avoid the possibility of an empty <parameter>dst</parameter> result:
   </para><para>

   unsigned long *tmp;	// a temporary bitmap's bits
   </para><para>

   bitmap_fold(tmp, orig, bitmap_weight(relmap, bits), bits);
   bitmap_onto(dst, tmp, relmap, bits);
   </para><para>

   Then this table shows what various values of <parameter>dst</parameter> would be, for
   various <parameter>orig</parameter>'s.  I list the zero-based positions of each set bit.
   The tmp column shows the intermediate result, as computed by
   using <function>bitmap_fold</function> to fold the <parameter>orig</parameter> bitmap modulo ten
   (the weight of <parameter>relmap</parameter>).
   </para><para>

   <parameter>orig</parameter>           tmp            <parameter>dst</parameter>
   0                0             40
   1                1             41
   9                9             95
   10               0             40 (*)
   1 3 5 7          1 3 5 7       41 43 48 61
   0 1 2 3 4        0 1 2 3 4     40 41 42 43 45
   0 9 18 27        0 9 8 7       40 61 74 95
   0 10 20 30       0             40
   0 11 22 33       0 1 2 3       40 41 42 43
   0 12 24 36       0 2 4 6       40 42 45 53
   78 102 211       1 2 8         41 42 74 (*)
   </para><para>

   (*) For these marked lines, if we hadn't first done <function>bitmap_fold</function>
   into tmp, then the <parameter>dst</parameter> result would have been empty.
   </para><para>

   If either of <parameter>orig</parameter> or <parameter>relmap</parameter> is empty (no set bits), then <parameter>dst</parameter>
   will be returned empty.
   </para><para>

   If (as explained above) the only set bits in <parameter>orig</parameter> are in positions
   m where m &gt;= W, (where W is the weight of <parameter>relmap</parameter>) then <parameter>dst</parameter> will
   once again be returned empty.
   </para><para>

   All bits in <parameter>dst</parameter> not set by the above rule are cleared.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-fold">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_fold</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_fold</refname>
 <refpurpose>
     fold larger bitmap into smaller, modulo specified size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>bitmap_fold </function></funcdef>
   <paramdef>unsigned long * <parameter>dst</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>orig</parameter></paramdef>
   <paramdef>unsigned int <parameter>sz</parameter></paramdef>
   <paramdef>unsigned int <parameter>nbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     resulting smaller bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>orig</parameter></term>
   <listitem>
    <para>
     original larger bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sz</parameter></term>
   <listitem>
    <para>
     specified size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nbits</parameter></term>
   <listitem>
    <para>
     number of bits in each of these bitmaps
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   For each bit oldbit in <parameter>orig</parameter>, set bit oldbit mod <parameter>sz</parameter> in <parameter>dst</parameter>.
   Clear all other bits in <parameter>dst</parameter>.  See further the comment and
   Example [2] for <function>bitmap_onto</function> for why and how to use this.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-find-free-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_find_free_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_find_free_region</refname>
 <refpurpose>
     find a contiguous aligned mem region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bitmap_find_free_region </function></funcdef>
   <paramdef>unsigned long * <parameter>bitmap</parameter></paramdef>
   <paramdef>unsigned int <parameter>bits</parameter></paramdef>
   <paramdef>int <parameter>order</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bitmap</parameter></term>
   <listitem>
    <para>
     array of unsigned longs corresponding to the bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bits</parameter></term>
   <listitem>
    <para>
     number of bits in the bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>order</parameter></term>
   <listitem>
    <para>
     region size (log base 2 of number of bits) to find
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Find a region of free (zero) bits in a <parameter>bitmap</parameter> of <parameter>bits</parameter> bits and
   allocate them (set them to one).  Only consider regions of length
   a power (<parameter>order</parameter>) of two, aligned to that power of two, which
   makes the search algorithm much faster.
   </para><para>

   Return the bit offset in bitmap of the allocated region,
   or -errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-release-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_release_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_release_region</refname>
 <refpurpose>
     release allocated bitmap region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>bitmap_release_region </function></funcdef>
   <paramdef>unsigned long * <parameter>bitmap</parameter></paramdef>
   <paramdef>unsigned int <parameter>pos</parameter></paramdef>
   <paramdef>int <parameter>order</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bitmap</parameter></term>
   <listitem>
    <para>
     array of unsigned longs corresponding to the bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     beginning of bit region to release
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>order</parameter></term>
   <listitem>
    <para>
     region size (log base 2 of number of bits) to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the complement to <function>__bitmap_find_free_region</function> and releases
   the found region (by clearing it in the bitmap).
   </para><para>

   No return value.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-allocate-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_allocate_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_allocate_region</refname>
 <refpurpose>
     allocate bitmap region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bitmap_allocate_region </function></funcdef>
   <paramdef>unsigned long * <parameter>bitmap</parameter></paramdef>
   <paramdef>unsigned int <parameter>pos</parameter></paramdef>
   <paramdef>int <parameter>order</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bitmap</parameter></term>
   <listitem>
    <para>
     array of unsigned longs corresponding to the bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     beginning of bit region to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>order</parameter></term>
   <listitem>
    <para>
     region size (log base 2 of number of bits) to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate (set bits in) a specified region of a bitmap.
   </para><para>

   Return 0 on success, or <constant>-EBUSY</constant> if specified region wasn't
   free (not all bits were zero).
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-copy-le">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_copy_le</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_copy_le</refname>
 <refpurpose>
     copy a bitmap, putting the bits into little-endian order.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>bitmap_copy_le </function></funcdef>
   <paramdef>unsigned long * <parameter>dst</parameter></paramdef>
   <paramdef>const unsigned long * <parameter>src</parameter></paramdef>
   <paramdef>unsigned int <parameter>nbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     destination buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     bitmap to copy
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nbits</parameter></term>
   <listitem>
    <para>
     number of bits in the bitmap
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Require nbits % BITS_PER_LONG == 0.
</para>
</refsect1>
</refentry>

<!-- lib/bitmap.c -->
<refentry id="API---bitmap-parselist">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__bitmap_parselist</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__bitmap_parselist</refname>
 <refpurpose>
  convert list format ASCII string to bitmap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__bitmap_parselist </function></funcdef>
   <paramdef>const char * <parameter>buf</parameter></paramdef>
   <paramdef>unsigned int <parameter>buflen</parameter></paramdef>
   <paramdef>int <parameter>is_user</parameter></paramdef>
   <paramdef>unsigned long * <parameter>maskp</parameter></paramdef>
   <paramdef>int <parameter>nmaskbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     read nul-terminated user string from this buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buflen</parameter></term>
   <listitem>
    <para>
     buffer size in bytes.  If string is smaller than this
     then it must be terminated with a \0.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>is_user</parameter></term>
   <listitem>
    <para>
     location of buffer, 0 indicates kernel space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maskp</parameter></term>
   <listitem>
    <para>
     write resulting mask here
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nmaskbits</parameter></term>
   <listitem>
    <para>
     number of bits in mask to be written
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Input format is a comma-separated list of decimal numbers and
   ranges.  Consecutively set bits are shown as two hyphen-separated
   decimal numbers, the smallest and largest bit numbers set in
   the range.
   </para><para>

   Returns 0 on success, -errno on invalid input strings.
</para>
</refsect1>
<refsect1>
<title>Error values</title>
<para>
   <constant>-EINVAL</constant>: second number in range smaller than first
   <constant>-EINVAL</constant>: invalid character in string
   <constant>-ERANGE</constant>: bit number specified too large for mask
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-pos-to-ord">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_pos_to_ord</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_pos_to_ord</refname>
 <refpurpose>
     find ordinal of set bit at given position in bitmap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bitmap_pos_to_ord </function></funcdef>
   <paramdef>const unsigned long * <parameter>buf</parameter></paramdef>
   <paramdef>unsigned int <parameter>pos</parameter></paramdef>
   <paramdef>unsigned int <parameter>nbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     pointer to a bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     a bit position in <parameter>buf</parameter> (0 &lt;= <parameter>pos</parameter> &lt; <parameter>nbits</parameter>)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nbits</parameter></term>
   <listitem>
    <para>
     number of valid bit positions in <parameter>buf</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Map the bit at position <parameter>pos</parameter> in <parameter>buf</parameter> (of length <parameter>nbits</parameter>) to the
   ordinal of which set bit it is.  If it is not set or if <parameter>pos</parameter>
   is not a valid bit position, map to -1.
   </para><para>

   If for example, just bits 4 through 7 are set in <parameter>buf</parameter>, then <parameter>pos</parameter>
   values 4 through 7 will get mapped to 0 through 3, respectively,
   and other <parameter>pos</parameter> values will get mapped to -1.  When <parameter>pos</parameter> value 7
   gets mapped to (returns) <parameter>ord</parameter> value 3 in this example, that means
   that bit 7 is the 3rd (starting with 0th) set bit in <parameter>buf</parameter>.
   </para><para>

   The bit positions 0 through <parameter>bits</parameter> are valid positions in <parameter>buf</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-ord-to-pos">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_ord_to_pos</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_ord_to_pos</refname>
 <refpurpose>
     find position of n-th set bit in bitmap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>bitmap_ord_to_pos </function></funcdef>
   <paramdef>const unsigned long * <parameter>buf</parameter></paramdef>
   <paramdef>unsigned int <parameter>ord</parameter></paramdef>
   <paramdef>unsigned int <parameter>nbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     pointer to bitmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ord</parameter></term>
   <listitem>
    <para>
     ordinal bit position (n-th set bit, n &gt;= 0)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nbits</parameter></term>
   <listitem>
    <para>
     number of valid bit positions in <parameter>buf</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Map the ordinal offset of bit <parameter>ord</parameter> in <parameter>buf</parameter> to its position in <parameter>buf</parameter>.
   Value of <parameter>ord</parameter> should be in range 0 &lt;= <parameter>ord</parameter> &lt; weight(buf). If <parameter>ord</parameter>
   &gt;= weight(buf), returns <parameter>nbits</parameter>.
   </para><para>

   If for example, just bits 4 through 7 are set in <parameter>buf</parameter>, then <parameter>ord</parameter>
   values 0 through 3 will get mapped to 4 through 7, respectively,
   and all other <parameter>ord</parameter> values returns <parameter>nbits</parameter>.  When <parameter>ord</parameter> value 3
   gets mapped to (returns) <parameter>pos</parameter> value 7 in this example, that means
   that the 3rd set bit (starting with 0th) is at position 7 in <parameter>buf</parameter>.
   </para><para>

   The bit positions 0 through <parameter>nbits</parameter>-1 are valid positions in <parameter>buf</parameter>.
</para>
</refsect1>
</refentry>

     </sect1>

     <sect1><title>Command-line Parsing</title>
<!-- lib/cmdline.c -->
<refentry id="API-get-option">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_option</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_option</refname>
 <refpurpose>
  Parse integer from an option string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>get_option </function></funcdef>
   <paramdef>char ** <parameter>str</parameter></paramdef>
   <paramdef>int * <parameter>pint</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>str</parameter></term>
   <listitem>
    <para>
     option string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pint</parameter></term>
   <listitem>
    <para>
     (output) integer value parsed from <parameter>str</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Read an int from an option string; if available accept a subsequent
   comma as well.
</para>
</refsect1>
<refsect1>
<title>Return values</title>
<para>
   0 - no int in string
   1 - int found, no subsequent comma
   2 - int found including a subsequent comma
   3 - hyphen found to denote a range
</para>
</refsect1>
</refentry>

<refentry id="API-get-options">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_options</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_options</refname>
 <refpurpose>
     Parse a string into a list of integers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>get_options </function></funcdef>
   <paramdef>const char * <parameter>str</parameter></paramdef>
   <paramdef>int <parameter>nints</parameter></paramdef>
   <paramdef>int * <parameter>ints</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>str</parameter></term>
   <listitem>
    <para>
     String to be parsed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nints</parameter></term>
   <listitem>
    <para>
     size of integer array
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ints</parameter></term>
   <listitem>
    <para>
     integer array
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function parses a string containing a comma-separated
   list of integers, a hyphen-separated range of _positive_ integers,
   or a combination of both.  The parse halts when the array is
   full, or when no more numbers can be retrieved from the
   string.
   </para><para>

   Return value is the character in the string which caused
   the parse to end (typically a null terminator, if <parameter>str</parameter> is
   completely parseable).
</para>
</refsect1>
</refentry>

<refentry id="API-memparse">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memparse</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>memparse</refname>
 <refpurpose>
     parse a string with mem suffixes into a number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long long <function>memparse </function></funcdef>
   <paramdef>const char * <parameter>ptr</parameter></paramdef>
   <paramdef>char ** <parameter>retptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     Where parse begins
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>retptr</parameter></term>
   <listitem>
    <para>
     (output) Optional pointer to next char after parse completes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Parses a string into a number.  The number stored at <parameter>ptr</parameter> is
   potentially suffixed with K, M, G, T, P, E.
</para>
</refsect1>
</refentry>

     </sect1>

     <sect1 id="crc"><title>CRC Functions</title>
<!-- lib/crc7.c -->
<refentry id="API-crc7-be">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>crc7_be</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>crc7_be</refname>
 <refpurpose>
  update the CRC7 for the data buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u8 <function>crc7_be </function></funcdef>
   <paramdef>u8 <parameter>crc</parameter></paramdef>
   <paramdef>const u8 * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crc</parameter></term>
   <listitem>
    <para>
     previous CRC7 value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     data pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes in the buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   any
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the updated CRC7 value.
   The CRC7 is left-aligned in the byte (the lsbit is always 0), as that
   makes the computation easier, and all callers want it in that form.
</para>
</refsect1>
</refentry>

<!-- lib/crc16.c -->
<refentry id="API-crc16">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>crc16</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>crc16</refname>
 <refpurpose>
  compute the CRC-16 for the data buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u16 <function>crc16 </function></funcdef>
   <paramdef>u16 <parameter>crc</parameter></paramdef>
   <paramdef>u8 const * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crc</parameter></term>
   <listitem>
    <para>
     previous CRC value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     data pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes in the buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the updated CRC value.
</para>
</refsect1>
</refentry>

<!-- lib/crc-itu-t.c -->
<refentry id="API-crc-itu-t">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>crc_itu_t</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>crc_itu_t</refname>
 <refpurpose>
  Compute the CRC-ITU-T for the data buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u16 <function>crc_itu_t </function></funcdef>
   <paramdef>u16 <parameter>crc</parameter></paramdef>
   <paramdef>const u8 * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crc</parameter></term>
   <listitem>
    <para>
     previous CRC value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     data pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes in the buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the updated CRC value
</para>
</refsect1>
</refentry>

<!-- lib/crc32.c -->
<refentry>
 <refnamediv>
  <refname>
   .//lib/crc32.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>.//lib/crc32.c</filename> at this point,
    but none was found.
    This dummy section is inserted to allow
    generation to continue.
   </para>
  </warning>
 </refsect1>
</refentry>
<!-- lib/crc-ccitt.c -->
<refentry id="API-crc-ccitt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>crc_ccitt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>crc_ccitt</refname>
 <refpurpose>
  recompute the CRC for the data buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u16 <function>crc_ccitt </function></funcdef>
   <paramdef>u16 <parameter>crc</parameter></paramdef>
   <paramdef>u8 const * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crc</parameter></term>
   <listitem>
    <para>
     previous CRC value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     data pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes in the buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>

     <sect1 id="idr"><title>idr/ida Functions</title>
<para>
   idr synchronization (stolen from radix-tree.h)
   </para><para>
   <function>idr_find</function> is able to be called locklessly, using RCU. The caller must
   ensure calls to this function are made within <function>rcu_read_lock</function> regions.
   Other readers (lock-free or otherwise) and modifications may be running
   concurrently.
   </para><para>
   It is still required that the caller manage the synchronization and
   lifetimes of the items. So if RCU lock-free lookups are used, typically
   this would mean that the items have their own locks, or are amenable to
   lock-free access; and that the items are freed by RCU (or only freed after
   having been deleted from the idr tree *and* a <function>synchronize_rcu</function> grace
   period).
</para>

<para>
   IDA - IDR based ID allocator
   </para><para>
   This is id allocator without id -&gt; pointer translation.  Memory
   usage is much lower than full blown idr because each id only
   occupies a bit.  ida uses a custom leaf node which contains
   IDA_BITMAP_BITS slots.
   </para><para>
   2007-04-25  written by Tejun Heo &lt;htejun<parameter>gmail</parameter>.com&gt;
</para>

<!-- lib/idr.c -->
<refentry id="API-idr-preload">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>idr_preload</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>idr_preload</refname>
 <refpurpose>
  preload for <function>idr_alloc</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>idr_preload </function></funcdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     allocation mask to use for preloading
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Preload per-cpu layer buffer for <function>idr_alloc</function>.  Can only be used from
   process context and each <function>idr_preload</function> invocation should be matched with
   <function>idr_preload_end</function>.  Note that preemption is disabled while preloaded.
   </para><para>

   The first <function>idr_alloc</function> in the preloaded section can be treated as if it
   were invoked with <parameter>gfp_mask</parameter> used for preloading.  This allows using more
   permissive allocation masks for idrs protected by spinlocks.
   </para><para>

   For example, if <function>idr_alloc</function> below fails, the failure can be treated as
   if <function>idr_alloc</function> were called with GFP_KERNEL rather than GFP_NOWAIT.
   </para><para>

   idr_preload(GFP_KERNEL);
   spin_lock(lock);
   </para><para>

   id = idr_alloc(idr, ptr, start, end, GFP_NOWAIT);
   </para><para>

   spin_unlock(lock);
   <function>idr_preload_end</function>;
   if (id &lt; 0)
   error;
</para>
</refsect1>
</refentry>

<refentry id="API-idr-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>idr_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>idr_alloc</refname>
 <refpurpose>
     allocate new idr entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>idr_alloc </function></funcdef>
   <paramdef>struct idr * <parameter>idr</parameter></paramdef>
   <paramdef>void * <parameter>ptr</parameter></paramdef>
   <paramdef>int <parameter>start</parameter></paramdef>
   <paramdef>int <parameter>end</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>idr</parameter></term>
   <listitem>
    <para>
     the (initialized) idr
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer to be associated with the new id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     the minimum id (inclusive)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     the maximum id (exclusive, &lt;= 0 for max)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate an id in [start, end) and associate it with <parameter>ptr</parameter>.  If no ID is
   available in the specified range, returns -ENOSPC.  On memory allocation
   failure, returns -ENOMEM.
   </para><para>

   Note that <parameter>end</parameter> is treated as max when &lt;= 0.  This is to always allow
   using <parameter>start</parameter> + N as <parameter>end</parameter> as long as N is inside integer range.
   </para><para>

   The user is responsible for exclusively synchronizing all operations
   which may modify <parameter>idr</parameter>.  However, read-only accesses such as <function>idr_find</function>
   or iteration can be performed under RCU read lock provided the user
   destroys <parameter>ptr</parameter> in RCU-safe way after removal from idr.
</para>
</refsect1>
</refentry>

<refentry id="API-idr-alloc-cyclic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>idr_alloc_cyclic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>idr_alloc_cyclic</refname>
 <refpurpose>
     allocate new idr entry in a cyclical fashion
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>idr_alloc_cyclic </function></funcdef>
   <paramdef>struct idr * <parameter>idr</parameter></paramdef>
   <paramdef>void * <parameter>ptr</parameter></paramdef>
   <paramdef>int <parameter>start</parameter></paramdef>
   <paramdef>int <parameter>end</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>idr</parameter></term>
   <listitem>
    <para>
     the (initialized) idr
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer to be associated with the new id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     the minimum id (inclusive)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     the maximum id (exclusive, &lt;= 0 for max)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Essentially the same as idr_alloc, but prefers to allocate progressively
   higher ids if it can. If the <quote>cur</quote> counter wraps, then it will start again
   at the <quote>start</quote> end of the range and allocate one that has already been used.
</para>
</refsect1>
</refentry>

<refentry id="API-idr-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>idr_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>idr_remove</refname>
 <refpurpose>
     remove the given id and free its slot
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>idr_remove </function></funcdef>
   <paramdef>struct idr * <parameter>idp</parameter></paramdef>
   <paramdef>int <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>idp</parameter></term>
   <listitem>
    <para>
     idr handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     unique key
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-idr-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>idr_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>idr_destroy</refname>
 <refpurpose>
     release all cached layers within an idr tree
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>idr_destroy </function></funcdef>
   <paramdef>struct idr * <parameter>idp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>idp</parameter></term>
   <listitem>
    <para>
     idr handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free all id mappings and all idp_layers.  After this function, <parameter>idp</parameter> is
   completely unused and can be freed / recycled.  The caller is
   responsible for ensuring that no one else accesses <parameter>idp</parameter> during or after
   <function>idr_destroy</function>.
   </para><para>

   A typical clean-up sequence for objects stored in an idr tree will use
   <function>idr_for_each</function> to free all objects, if necessary, then <function>idr_destroy</function> to
   free up the id mappings and cached idr_layers.
</para>
</refsect1>
</refentry>

<refentry id="API-idr-for-each">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>idr_for_each</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>idr_for_each</refname>
 <refpurpose>
     iterate through all stored pointers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>idr_for_each </function></funcdef>
   <paramdef>struct idr * <parameter>idp</parameter></paramdef>
   <paramdef>int (*<parameter>fn</parameter>)
     <funcparams>int id, void *p, void *data</funcparams></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>idp</parameter></term>
   <listitem>
    <para>
     idr handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fn</parameter></term>
   <listitem>
    <para>
     function to be called for each pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data passed back to callback function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over the pointers registered with the given idr.  The
   callback function will be called for each pointer currently
   registered, passing the id, the pointer and the data pointer passed
   to this function.  It is not safe to modify the idr tree while in
   the callback, so functions such as idr_get_new and idr_remove are
   not allowed.
   </para><para>

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

   The caller must serialize <function>idr_for_each</function> vs <function>idr_get_new</function> and <function>idr_remove</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-idr-get-next">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>idr_get_next</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>idr_get_next</refname>
 <refpurpose>
     lookup next object of id to given id.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>idr_get_next </function></funcdef>
   <paramdef>struct idr * <parameter>idp</parameter></paramdef>
   <paramdef>int * <parameter>nextidp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>idp</parameter></term>
   <listitem>
    <para>
     idr handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nextidp</parameter></term>
   <listitem>
    <para>
     pointer to lookup key
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns pointer to registered object with id, which is next number to
   given id. After being looked up, *<parameter>nextidp</parameter> will be updated for the next
   iteration.
   </para><para>

   This function can be called under <function>rcu_read_lock</function>, given that the leaf
   pointers lifetimes are correctly managed.
</para>
</refsect1>
</refentry>

<refentry id="API-idr-replace">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>idr_replace</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>idr_replace</refname>
 <refpurpose>
     replace pointer for given id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>idr_replace </function></funcdef>
   <paramdef>struct idr * <parameter>idp</parameter></paramdef>
   <paramdef>void * <parameter>ptr</parameter></paramdef>
   <paramdef>int <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>idp</parameter></term>
   <listitem>
    <para>
     idr handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer you want associated with the id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     lookup key
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Replace the pointer registered with an id and return the old value.
   A <constant>-ENOENT</constant> return indicates that <parameter>id</parameter> was not found.
   A <constant>-EINVAL</constant> return indicates that <parameter>id</parameter> was not within valid constraints.
   </para><para>

   The caller must serialize with writers.
</para>
</refsect1>
</refentry>

<refentry id="API-idr-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>idr_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>idr_init</refname>
 <refpurpose>
     initialize idr handle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>idr_init </function></funcdef>
   <paramdef>struct idr * <parameter>idp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>idp</parameter></term>
   <listitem>
    <para>
     idr handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is use to set up the handle (<parameter>idp</parameter>) that you will pass
   to the rest of the functions.
</para>
</refsect1>
</refentry>

<refentry id="API-ida-pre-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ida_pre_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ida_pre_get</refname>
 <refpurpose>
     reserve resources for ida allocation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ida_pre_get </function></funcdef>
   <paramdef>struct ida * <parameter>ida</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ida</parameter></term>
   <listitem>
    <para>
     ida handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation flag
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should be called prior to locking and calling the
   following function.  It preallocates enough memory to satisfy the
   worst possible allocation.
   </para><para>

   If the system is REALLY out of memory this function returns <constant>0</constant>,
   otherwise <constant>1</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API-ida-get-new-above">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ida_get_new_above</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ida_get_new_above</refname>
 <refpurpose>
     allocate new ID above or equal to a start id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ida_get_new_above </function></funcdef>
   <paramdef>struct ida * <parameter>ida</parameter></paramdef>
   <paramdef>int <parameter>starting_id</parameter></paramdef>
   <paramdef>int * <parameter>p_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ida</parameter></term>
   <listitem>
    <para>
     ida handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>starting_id</parameter></term>
   <listitem>
    <para>
     id to start search at
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>p_id</parameter></term>
   <listitem>
    <para>
     pointer to the allocated handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate new ID above or equal to <parameter>starting_id</parameter>.  It should be called
   with any required locks.
   </para><para>

   If memory is required, it will return <constant>-EAGAIN</constant>, you should unlock
   and go back to the <function>ida_pre_get</function> call.  If the ida is full, it will
   return <constant>-ENOSPC</constant>.
   </para><para>

   <parameter>p_id</parameter> returns a value in the range <parameter>starting_id</parameter> ... <constant>0x7fffffff</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API-ida-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ida_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ida_remove</refname>
 <refpurpose>
     remove the given ID
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ida_remove </function></funcdef>
   <paramdef>struct ida * <parameter>ida</parameter></paramdef>
   <paramdef>int <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ida</parameter></term>
   <listitem>
    <para>
     ida handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     ID to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-ida-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ida_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ida_destroy</refname>
 <refpurpose>
     release all cached layers within an ida tree
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ida_destroy </function></funcdef>
   <paramdef>struct ida * <parameter>ida</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ida</parameter></term>
   <listitem>
    <para>
     ida handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-ida-simple-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ida_simple_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ida_simple_get</refname>
 <refpurpose>
     get a new id.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ida_simple_get </function></funcdef>
   <paramdef>struct ida * <parameter>ida</parameter></paramdef>
   <paramdef>unsigned int <parameter>start</parameter></paramdef>
   <paramdef>unsigned int <parameter>end</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ida</parameter></term>
   <listitem>
    <para>
     the (initialized) ida.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     the minimum id (inclusive, &lt; 0x8000000)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     the maximum id (exclusive, &lt; 0x8000000 or 0)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates an id in the range start &lt;= id &lt; end, or returns -ENOSPC.
   On memory allocation failure, returns -ENOMEM.
   </para><para>

   Use <function>ida_simple_remove</function> to get rid of an id.
</para>
</refsect1>
</refentry>

<refentry id="API-ida-simple-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ida_simple_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ida_simple_remove</refname>
 <refpurpose>
     remove an allocated id.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ida_simple_remove </function></funcdef>
   <paramdef>struct ida * <parameter>ida</parameter></paramdef>
   <paramdef>unsigned int <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ida</parameter></term>
   <listitem>
    <para>
     the (initialized) ida.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the id returned by ida_simple_get.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-ida-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ida_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ida_init</refname>
 <refpurpose>
     initialize ida handle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ida_init </function></funcdef>
   <paramdef>struct ida * <parameter>ida</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ida</parameter></term>
   <listitem>
    <para>
     ida handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is use to set up the handle (<parameter>ida</parameter>) that you will pass
   to the rest of the functions.
</para>
</refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="mm">
     <title>Memory Management in Linux</title>
     <sect1><title>The Slab Cache</title>
<!-- include/linux/slab.h -->
<refentry id="API-kmalloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmalloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmalloc</refname>
 <refpurpose>
  allocate memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>kmalloc </function></funcdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     how many bytes of memory are required.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     the type of memory to allocate.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   kmalloc is the normal method of allocating memory
   for objects smaller than page size in the kernel.
   </para><para>

   The <parameter>flags</parameter> argument may be one of:
   </para><para>

   <constant>GFP_USER</constant> - Allocate memory on behalf of user.  May sleep.
   </para><para>

   <constant>GFP_KERNEL</constant> - Allocate normal kernel ram.  May sleep.
   </para><para>

   <constant>GFP_ATOMIC</constant> - Allocation will not sleep.  May use emergency pools.
   For example, use this inside interrupt handlers.
   </para><para>

   <constant>GFP_HIGHUSER</constant> - Allocate pages from high memory.
   </para><para>

   <constant>GFP_NOIO</constant> - Do not do any I/O at all while trying to get memory.
   </para><para>

   <constant>GFP_NOFS</constant> - Do not make any fs calls while trying to get memory.
   </para><para>

   <constant>GFP_NOWAIT</constant> - Allocation will not sleep.
   </para><para>

   <constant>__GFP_THISNODE</constant> - Allocate node-local memory only.
   </para><para>

   <constant>GFP_DMA</constant> - Allocation suitable for DMA.
   Should only be used for <function>kmalloc</function> caches. Otherwise, use a
   slab created with SLAB_DMA.
   </para><para>

   Also it is possible to set different flags by OR'ing
   in one or more of the following additional <parameter>flags</parameter>:
   </para><para>

   <constant>__GFP_COLD</constant> - Request cache-cold pages instead of
   trying to return cache-warm pages.
   </para><para>

   <constant>__GFP_HIGH</constant> - This allocation has high priority and may use emergency pools.
   </para><para>

   <constant>__GFP_NOFAIL</constant> - Indicate that this allocation is in no way allowed to fail
   (think twice before using).
   </para><para>

   <constant>__GFP_NORETRY</constant> - If memory is not immediately available,
   then give up at once.
   </para><para>

   <constant>__GFP_NOWARN</constant> - If allocation fails, don't issue any warnings.
   </para><para>

   <constant>__GFP_REPEAT</constant> - If allocation fails initially, try once more before failing.
   </para><para>

   There are other flags available as well, but these are not intended
   for general use, and so are not documented here. For a full list of
   potential flags, always refer to linux/gfp.h.
</para>
</refsect1>
</refentry>

<refentry id="API-kmalloc-array">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmalloc_array</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmalloc_array</refname>
 <refpurpose>
     allocate memory for an array.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>kmalloc_array </function></funcdef>
   <paramdef>size_t <parameter>n</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     number of elements.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     element size.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     the type of memory to allocate (see kmalloc).
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kcalloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kcalloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kcalloc</refname>
 <refpurpose>
     allocate memory for an array. The memory is set to zero.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>kcalloc </function></funcdef>
   <paramdef>size_t <parameter>n</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     number of elements.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     element size.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     the type of memory to allocate (see kmalloc).
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kzalloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kzalloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kzalloc</refname>
 <refpurpose>
     allocate memory. The memory is set to zero.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>kzalloc </function></funcdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     how many bytes of memory are required.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     the type of memory to allocate (see kmalloc).
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kzalloc-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kzalloc_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kzalloc_node</refname>
 <refpurpose>
     allocate zeroed memory from a particular memory node.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>kzalloc_node </function></funcdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>flags</parameter></paramdef>
   <paramdef>int <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     how many bytes of memory are required.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     the type of memory to allocate (see kmalloc).
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     memory node from which to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- mm/slab.c -->
<refentry id="API-kmem-cache-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmem_cache_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmem_cache_alloc</refname>
 <refpurpose>
  Allocate an object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>kmem_cache_alloc </function></funcdef>
   <paramdef>struct kmem_cache * <parameter>cachep</parameter></paramdef>
   <paramdef>gfp_t <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cachep</parameter></term>
   <listitem>
    <para>
     The cache to allocate from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     See <function>kmalloc</function>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate an object from this cache.  The flags are only relevant
   if the cache has no available objects.
</para>
</refsect1>
</refentry>

<refentry id="API-kmem-cache-alloc-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmem_cache_alloc_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmem_cache_alloc_node</refname>
 <refpurpose>
     Allocate an object on the specified node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>kmem_cache_alloc_node </function></funcdef>
   <paramdef>struct kmem_cache * <parameter>cachep</parameter></paramdef>
   <paramdef>gfp_t <parameter>flags</parameter></paramdef>
   <paramdef>int <parameter>nodeid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cachep</parameter></term>
   <listitem>
    <para>
     The cache to allocate from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     See <function>kmalloc</function>.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nodeid</parameter></term>
   <listitem>
    <para>
     node number of the target node.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Identical to kmem_cache_alloc but it will allocate memory on the given
   node, which can improve the performance for cpu bound structures.
   </para><para>

   Fallback to other node is possible if __GFP_THISNODE is not set.
</para>
</refsect1>
</refentry>

<refentry id="API-kmem-cache-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmem_cache_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmem_cache_free</refname>
 <refpurpose>
     Deallocate an object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kmem_cache_free </function></funcdef>
   <paramdef>struct kmem_cache * <parameter>cachep</parameter></paramdef>
   <paramdef>void * <parameter>objp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cachep</parameter></term>
   <listitem>
    <para>
     The cache the allocation was from.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>objp</parameter></term>
   <listitem>
    <para>
     The previously allocated object.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free an object which was previously allocated from this
   cache.
</para>
</refsect1>
</refentry>

<refentry id="API-kfree">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfree</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfree</refname>
 <refpurpose>
     free previously allocated memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kfree </function></funcdef>
   <paramdef>const void * <parameter>objp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>objp</parameter></term>
   <listitem>
    <para>
     pointer returned by kmalloc.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If <parameter>objp</parameter> is NULL, no operation is performed.
   </para><para>

   Don't free memory not originally allocated by <function>kmalloc</function>
   or you will run into trouble.
</para>
</refsect1>
</refentry>

<refentry id="API-ksize">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ksize</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ksize</refname>
 <refpurpose>
     get the actual amount of memory allocated for a given object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>ksize </function></funcdef>
   <paramdef>const void * <parameter>objp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>objp</parameter></term>
   <listitem>
    <para>
     Pointer to the object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   kmalloc may internally round up allocations and return more memory
   than requested. <function>ksize</function> can be used to determine the actual amount of
   memory allocated. The caller may use this additional memory, even though
   a smaller amount of memory was initially specified with the kmalloc call.
   The caller must guarantee that objp points to a valid object previously
   allocated with either <function>kmalloc</function> or <function>kmem_cache_alloc</function>. The object
   must not be freed during the duration of the call.
</para>
</refsect1>
</refentry>

<!-- mm/util.c -->
<refentry id="API-kfree-const">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfree_const</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfree_const</refname>
 <refpurpose>
  conditionally free memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kfree_const </function></funcdef>
   <paramdef>const void * <parameter>x</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     pointer to the memory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Function calls kfree only if <parameter>x</parameter> is not in .rodata section.
</para>
</refsect1>
</refentry>

<refentry id="API-kstrdup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kstrdup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kstrdup</refname>
 <refpurpose>
     allocate space for and copy an existing string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>kstrdup </function></funcdef>
   <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>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>kmalloc</function> call when allocating memory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kstrdup-const">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kstrdup_const</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kstrdup_const</refname>
 <refpurpose>
     conditionally duplicate an existing const string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>kstrdup_const </function></funcdef>
   <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>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>kmalloc</function> call when allocating memory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Function returns source string if it is in .rodata section otherwise it
   fallbacks to kstrdup.
   Strings allocated by kstrdup_const should be freed by kfree_const.
</para>
</refsect1>
</refentry>

<refentry id="API-kstrndup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kstrndup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kstrndup</refname>
 <refpurpose>
     allocate space for and copy an existing string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>kstrndup </function></funcdef>
   <paramdef>const char * <parameter>s</parameter></paramdef>
   <paramdef>size_t <parameter>max</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     the string to duplicate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     read at most <parameter>max</parameter> chars from <parameter>s</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     the GFP mask used in the <function>kmalloc</function> call when allocating memory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kmemdup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmemdup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmemdup</refname>
 <refpurpose>
     duplicate region of memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>kmemdup </function></funcdef>
   <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>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>
</refentry>

<refentry id="API-memdup-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memdup_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>memdup_user</refname>
 <refpurpose>
     duplicate memory region from user space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>memdup_user </function></funcdef>
   <paramdef>const void __user * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     source address in user space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes to copy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns an <function>ERR_PTR</function> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-get-user-pages-fast">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_user_pages_fast</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_user_pages_fast</refname>
 <refpurpose>
     pin user pages in memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>get_user_pages_fast </function></funcdef>
   <paramdef>unsigned long <parameter>start</parameter></paramdef>
   <paramdef>int <parameter>nr_pages</parameter></paramdef>
   <paramdef>int <parameter>write</parameter></paramdef>
   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     starting user address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_pages</parameter></term>
   <listitem>
    <para>
     number of pages from start to pin
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>write</parameter></term>
   <listitem>
    <para>
     whether pages will be written to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     array that receives pointers to the pages pinned.
     Should be at least nr_pages long.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns number of pages pinned. This may be fewer than the number
   requested. If nr_pages is 0 or negative, returns 0. If no pages
   were pinned, returns -errno.
   </para><para>

   get_user_pages_fast provides equivalent functionality to get_user_pages,
   operating on current and current-&gt;mm, with force=0 and vma=NULL. However
   unlike get_user_pages, it must be called without mmap_sem held.
   </para><para>

   get_user_pages_fast may take mmap_sem and page table locks, so no
   assumptions can be made about lack of locking. get_user_pages_fast is to be
   implemented in a way that is advantageous (vs <function>get_user_pages</function>) when the
   user memory area is already faulted in and present in ptes. However if the
   pages have to be faulted in, it may turn out to be slightly slower so
   callers need to carefully consider what to use. On many architectures,
   get_user_pages_fast simply falls back to get_user_pages.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>User Space Memory Access</title>
<!-- arch/x86/include/asm/uaccess_32.h -->
<refentry id="API---copy-to-user-inatomic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__copy_to_user_inatomic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__copy_to_user_inatomic</refname>
 <refpurpose>
  Copy a block of data into user space, with less checking.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>__copy_to_user_inatomic </function></funcdef>
   <paramdef>void __user * <parameter>to</parameter></paramdef>
   <paramdef>const void * <parameter>from</parameter></paramdef>
   <paramdef>unsigned long <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     Destination address, in user space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     Source address, in kernel space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     Number of bytes to copy.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   User context only.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copy data from kernel space to user space.  Caller must check
   the specified block with <function>access_ok</function> before calling this function.
   The caller should also make sure he pins the user space address
   so that we don't result in page fault and sleep.
   </para><para>

   Here we special-case 1, 2 and 4-byte copy_*_user invocations.  On a fault
   we return the initial request size (1, 2 or 4), as copy_*_user should do.
   If a store crosses a page boundary and gets a fault, the x86 will not write
   anything, so this is accurate.
</para>
</refsect1>
</refentry>

<refentry id="API---copy-to-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__copy_to_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__copy_to_user</refname>
 <refpurpose>
     Copy a block of data into user space, with less checking.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>__copy_to_user </function></funcdef>
   <paramdef>void __user * <parameter>to</parameter></paramdef>
   <paramdef>const void * <parameter>from</parameter></paramdef>
   <paramdef>unsigned long <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     Destination address, in user space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     Source address, in kernel space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     Number of bytes to copy.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   User context only.  This function may sleep.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copy data from kernel space to user space.  Caller must check
   the specified block with <function>access_ok</function> before calling this function.
   </para><para>

   Returns number of bytes that could not be copied.
   On success, this will be zero.
</para>
</refsect1>
</refentry>

<refentry id="API---copy-from-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__copy_from_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__copy_from_user</refname>
 <refpurpose>
     Copy a block of data from user space, with less checking.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>__copy_from_user </function></funcdef>
   <paramdef>void * <parameter>to</parameter></paramdef>
   <paramdef>const void __user * <parameter>from</parameter></paramdef>
   <paramdef>unsigned long <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     Destination address, in kernel space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     Source address, in user space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     Number of bytes to copy.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   User context only.  This function may sleep.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copy data from user space to kernel space.  Caller must check
   the specified block with <function>access_ok</function> before calling this function.
   </para><para>

   Returns number of bytes that could not be copied.
   On success, this will be zero.
   </para><para>

   If some data could not be copied, this function will pad the copied
   data to the requested size using zero bytes.
   </para><para>

   An alternate version - <function>__copy_from_user_inatomic</function> - may be called from
   atomic context and will fail rather than sleep.  In this case the
   uncopied bytes will *NOT* be padded with zeros.  See fs/filemap.h
   for explanation of why this is needed.
</para>
</refsect1>
</refentry>

<!-- arch/x86/lib/usercopy_32.c -->
<refentry id="API-clear-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clear_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clear_user</refname>
 <refpurpose>
  Zero a block of memory in user space.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>clear_user </function></funcdef>
   <paramdef>void __user * <parameter>to</parameter></paramdef>
   <paramdef>unsigned long <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     Destination address, in user space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     Number of bytes to zero.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Zero a block of memory in user space.
   </para><para>

   Returns number of bytes that could not be cleared.
   On success, this will be zero.
</para>
</refsect1>
</refentry>

<refentry id="API---clear-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__clear_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__clear_user</refname>
 <refpurpose>
     Zero a block of memory in user space, with less checking.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>__clear_user </function></funcdef>
   <paramdef>void __user * <parameter>to</parameter></paramdef>
   <paramdef>unsigned long <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     Destination address, in user space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     Number of bytes to zero.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Zero a block of memory in user space.  Caller must check
   the specified block with <function>access_ok</function> before calling this function.
   </para><para>

   Returns number of bytes that could not be cleared.
   On success, this will be zero.
</para>
</refsect1>
</refentry>

<refentry id="API--copy-to-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>_copy_to_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>_copy_to_user</refname>
 <refpurpose>
     Copy a block of data into user space.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>_copy_to_user </function></funcdef>
   <paramdef>void __user * <parameter>to</parameter></paramdef>
   <paramdef>const void * <parameter>from</parameter></paramdef>
   <paramdef>unsigned <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     Destination address, in user space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     Source address, in kernel space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     Number of bytes to copy.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   User context only.  This function may sleep.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copy data from kernel space to user space.
   </para><para>

   Returns number of bytes that could not be copied.
   On success, this will be zero.
</para>
</refsect1>
</refentry>

<refentry id="API--copy-from-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>_copy_from_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>_copy_from_user</refname>
 <refpurpose>
     Copy a block of data from user space.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>_copy_from_user </function></funcdef>
   <paramdef>void * <parameter>to</parameter></paramdef>
   <paramdef>const void __user * <parameter>from</parameter></paramdef>
   <paramdef>unsigned <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     Destination address, in kernel space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     Source address, in user space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     Number of bytes to copy.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   User context only.  This function may sleep.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copy data from user space to kernel space.
   </para><para>

   Returns number of bytes that could not be copied.
   On success, this will be zero.
   </para><para>

   If some data could not be copied, this function will pad the copied
   data to the requested size using zero bytes.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>More Memory Management Functions</title>
<!-- mm/readahead.c -->
<refentry id="API-read-cache-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>read_cache_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>read_cache_pages</refname>
 <refpurpose>
  populate an address space with some pages &amp; start reads against them
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>read_cache_pages </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>struct list_head * <parameter>pages</parameter></paramdef>
   <paramdef>int (*<parameter>filler</parameter>)
     <funcparams>void *, struct page *</funcparams></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the address_space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     The address of a list_head which contains the target pages.  These
     pages have their -&gt;index populated and are otherwise uninitialised.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filler</parameter></term>
   <listitem>
    <para>
     callback routine for filling a single page.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     private data for the callback routine.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Hides the details of the LRU cache etc from the filesystems.
</para>
</refsect1>
</refentry>

<refentry id="API-page-cache-sync-readahead">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>page_cache_sync_readahead</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>page_cache_sync_readahead</refname>
 <refpurpose>
     generic file readahead
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>page_cache_sync_readahead </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>struct file_ra_state * <parameter>ra</parameter></paramdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>pgoff_t <parameter>offset</parameter></paramdef>
   <paramdef>unsigned long <parameter>req_size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     address_space which holds the pagecache and I/O vectors
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ra</parameter></term>
   <listitem>
    <para>
     file_ra_state which holds the readahead state
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     passed on to -&gt;<function>readpage</function> and -&gt;<function>readpages</function>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     start offset into <parameter>mapping</parameter>, in pagecache page-sized units
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>req_size</parameter></term>
   <listitem>
    <para>
     hint: total size of the read which the caller is performing in
     pagecache pages
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>page_cache_sync_readahead</function> should be called when a cache miss happened:
   it will submit the read.  The readahead logic may decide to piggyback more
   pages onto the read request if access patterns suggest it will improve
   performance.
</para>
</refsect1>
</refentry>

<refentry id="API-page-cache-async-readahead">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>page_cache_async_readahead</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>page_cache_async_readahead</refname>
 <refpurpose>
     file readahead for marked pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>page_cache_async_readahead </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>struct file_ra_state * <parameter>ra</parameter></paramdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
   <paramdef>pgoff_t <parameter>offset</parameter></paramdef>
   <paramdef>unsigned long <parameter>req_size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     address_space which holds the pagecache and I/O vectors
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ra</parameter></term>
   <listitem>
    <para>
     file_ra_state which holds the readahead state
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     passed on to -&gt;<function>readpage</function> and -&gt;<function>readpages</function>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     the page at <parameter>offset</parameter> which has the PG_readahead flag set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     start offset into <parameter>mapping</parameter>, in pagecache page-sized units
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>req_size</parameter></term>
   <listitem>
    <para>
     hint: total size of the read which the caller is performing in
     pagecache pages
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>page_cache_async_readahead</function> should be called when a page is used which
   has the PG_readahead flag; this is a marker to suggest that the application
   has used up enough of the readahead window that we should start pulling in
   more pages.
</para>
</refsect1>
</refentry>

<!-- mm/filemap.c -->
<refentry id="API-delete-from-page-cache">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>delete_from_page_cache</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>delete_from_page_cache</refname>
 <refpurpose>
  delete page from page cache
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>delete_from_page_cache </function></funcdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     the page which the kernel is trying to remove from page cache
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This must be called only on pages that have been verified to be in the page
   cache and locked.  It will never put the page into the free list, the caller
   has a reference on the page.
</para>
</refsect1>
</refentry>

<refentry id="API-filemap-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>filemap_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>filemap_flush</refname>
 <refpurpose>
     mostly a non-blocking flush
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>filemap_flush </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     target address_space
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a mostly non-blocking flush.  Not suitable for data-integrity
   purposes - I/O may not be started against all dirty pages.
</para>
</refsect1>
</refentry>

<refentry id="API-filemap-fdatawait-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>filemap_fdatawait_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>filemap_fdatawait_range</refname>
 <refpurpose>
     wait for writeback to complete
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>filemap_fdatawait_range </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>loff_t <parameter>start_byte</parameter></paramdef>
   <paramdef>loff_t <parameter>end_byte</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     address space structure to wait for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start_byte</parameter></term>
   <listitem>
    <para>
     offset in bytes where the range starts
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end_byte</parameter></term>
   <listitem>
    <para>
     offset in bytes where the range ends (inclusive)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Walk the list of under-writeback pages of the given address space
   in the given range and wait for all of them.
</para>
</refsect1>
</refentry>

<refentry id="API-filemap-fdatawait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>filemap_fdatawait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>filemap_fdatawait</refname>
 <refpurpose>
     wait for all under-writeback pages to complete
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>filemap_fdatawait </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     address space structure to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Walk the list of under-writeback pages of the given address space
   and wait for all of them.
</para>
</refsect1>
</refentry>

<refentry id="API-filemap-write-and-wait-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>filemap_write_and_wait_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>filemap_write_and_wait_range</refname>
 <refpurpose>
     write out &amp; wait on a file range
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>filemap_write_and_wait_range </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>loff_t <parameter>lstart</parameter></paramdef>
   <paramdef>loff_t <parameter>lend</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the address_space for the pages
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lstart</parameter></term>
   <listitem>
    <para>
     offset in bytes where the range starts
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lend</parameter></term>
   <listitem>
    <para>
     offset in bytes where the range ends (inclusive)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Write out and wait upon file offsets lstart-&gt;lend, inclusive.
   </para><para>

   Note that `lend' is inclusive (describes the last byte to be written) so
   that this function can be used to write to the very end-of-file (end = -1).
</para>
</refsect1>
</refentry>

<refentry id="API-replace-page-cache-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>replace_page_cache_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>replace_page_cache_page</refname>
 <refpurpose>
     replace a pagecache page with a new one
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>replace_page_cache_page </function></funcdef>
   <paramdef>struct page * <parameter>old</parameter></paramdef>
   <paramdef>struct page * <parameter>new</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     page to be replaced
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     page to replace with
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     allocation mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function replaces a page in the pagecache with a new one.  On
   success it acquires the pagecache reference for the new page and
   drops it for the old page.  Both the old and new pages must be
   locked.  This function does not add the new page to the LRU, the
   caller must do that.
   </para><para>

   The remove + add is atomic.  The only way this function can fail is
   memory allocation failure.
</para>
</refsect1>
</refentry>

<refentry id="API-add-to-page-cache-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>add_to_page_cache_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>add_to_page_cache_locked</refname>
 <refpurpose>
     add a locked page to the pagecache
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>add_to_page_cache_locked </function></funcdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>offset</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     page to add
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the page's address_space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     page index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     page allocation mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is used to add a page to the pagecache. It must be locked.
   This function does not add the page to the LRU.  The caller must do that.
</para>
</refsect1>
</refentry>

<refentry id="API-add-page-wait-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>add_page_wait_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>add_page_wait_queue</refname>
 <refpurpose>
     Add an arbitrary waiter to a page's wait queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>add_page_wait_queue </function></funcdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
   <paramdef>wait_queue_t * <parameter>waiter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     Page defining the wait queue of interest
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>waiter</parameter></term>
   <listitem>
    <para>
     Waiter to add to the queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add an arbitrary <parameter>waiter</parameter> to the wait queue for the nominated <parameter>page</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-unlock-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unlock_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unlock_page</refname>
 <refpurpose>
     unlock a locked page
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unlock_page </function></funcdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     the page
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unlocks the page and wakes up sleepers in <function>___wait_on_page_locked</function>.
   Also wakes sleepers in <function>wait_on_page_writeback</function> because the wakeup
   mechanism between PageLocked pages and PageWriteback pages is shared.
   But that's OK - sleepers in <function>wait_on_page_writeback</function> just go back to sleep.
   </para><para>

   The mb is necessary to enforce ordering between the clear_bit and the read
   of the waitqueue (to avoid SMP races with a parallel <function>wait_on_page_locked</function>).
</para>
</refsect1>
</refentry>

<refentry id="API-end-page-writeback">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>end_page_writeback</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>end_page_writeback</refname>
 <refpurpose>
     end writeback against a page
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>end_page_writeback </function></funcdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     the page
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---lock-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__lock_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__lock_page</refname>
 <refpurpose>
     get a lock on the page, assuming we need to sleep to get it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__lock_page </function></funcdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     the page to lock
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-page-cache-next-hole">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>page_cache_next_hole</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>page_cache_next_hole</refname>
 <refpurpose>
     find the next hole (not-present entry)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>pgoff_t <function>page_cache_next_hole </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>index</parameter></paramdef>
   <paramdef>unsigned long <parameter>max_scan</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     mapping
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>index</parameter></term>
   <listitem>
    <para>
     index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_scan</parameter></term>
   <listitem>
    <para>
     maximum range to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Search the set [index, min(index+max_scan-1, MAX_INDEX)] for the
   lowest indexed hole.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   the index of the hole if found, otherwise returns an index
   outside of the set specified (in which case 'return - index &gt;=
   max_scan' will be true). In rare cases of index wrap-around, 0 will
   be returned.
   </para><para>

   page_cache_next_hole may be called under rcu_read_lock. However,
   like radix_tree_gang_lookup, this will not atomically search a
   snapshot of the tree at a single point in time. For example, if a
   hole is created at index 5, then subsequently a hole is created at
   index 10, page_cache_next_hole covering both indexes may return 10
   if called under rcu_read_lock.
</para>
</refsect1>
</refentry>

<refentry id="API-page-cache-prev-hole">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>page_cache_prev_hole</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>page_cache_prev_hole</refname>
 <refpurpose>
     find the prev hole (not-present entry)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>pgoff_t <function>page_cache_prev_hole </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>index</parameter></paramdef>
   <paramdef>unsigned long <parameter>max_scan</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     mapping
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>index</parameter></term>
   <listitem>
    <para>
     index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_scan</parameter></term>
   <listitem>
    <para>
     maximum range to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Search backwards in the range [max(index-max_scan+1, 0), index] for
   the first hole.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   the index of the hole if found, otherwise returns an index
   outside of the set specified (in which case 'index - return &gt;=
   max_scan' will be true). In rare cases of wrap-around, ULONG_MAX
   will be returned.
   </para><para>

   page_cache_prev_hole may be called under rcu_read_lock. However,
   like radix_tree_gang_lookup, this will not atomically search a
   snapshot of the tree at a single point in time. For example, if a
   hole is created at index 10, then subsequently a hole is created at
   index 5, page_cache_prev_hole covering both indexes may return 5 if
   called under rcu_read_lock.
</para>
</refsect1>
</refentry>

<refentry id="API-find-get-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_get_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_get_entry</refname>
 <refpurpose>
     find and get a page cache entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>find_get_entry </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the address_space to search
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     the page cache index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Looks up the page cache slot at <parameter>mapping</parameter> &amp; <parameter>offset</parameter>.  If there is a
   page cache page, it is returned with an increased refcount.
   </para><para>

   If the slot holds a shadow entry of a previously evicted page, or a
   swap entry from shmem/tmpfs, it is returned.
   </para><para>

   Otherwise, <constant>NULL</constant> is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-find-lock-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_lock_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_lock_entry</refname>
 <refpurpose>
     locate, pin and lock a page cache entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>find_lock_entry </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the address_space to search
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     the page cache index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Looks up the page cache slot at <parameter>mapping</parameter> &amp; <parameter>offset</parameter>.  If there is a
   page cache page, it is returned locked and with an increased
   refcount.
   </para><para>

   If the slot holds a shadow entry of a previously evicted page, or a
   swap entry from shmem/tmpfs, it is returned.
   </para><para>

   Otherwise, <constant>NULL</constant> is returned.
   </para><para>

   <function>find_lock_entry</function> may sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-pagecache-get-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pagecache_get_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pagecache_get_page</refname>
 <refpurpose>
     find and get a page reference
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>pagecache_get_page </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>offset</parameter></paramdef>
   <paramdef>int <parameter>fgp_flags</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the address_space to search
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     the page index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fgp_flags</parameter></term>
   <listitem>
    <para>
     PCG flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     gfp mask to use for the page cache data page allocation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Looks up the page cache slot at <parameter>mapping</parameter> &amp; <parameter>offset</parameter>.
   </para><para>

   PCG flags modify how the page is returned.
</para>
</refsect1>
<refsect1>
<title>FGP_ACCESSED</title>
<para>
   the page will be marked accessed
</para>
</refsect1>
<refsect1>
<title>FGP_LOCK</title>
<para>
   Page is return locked
</para>
</refsect1>
<refsect1>
<title>FGP_CREAT</title>
<para>
   If page is not present then a new page is allocated using
   <parameter>gfp_mask</parameter> and added to the page cache and the VM's LRU
   list. The page is returned locked and with an increased
   refcount. Otherwise, <constant>NULL</constant> is returned.
   </para><para>

   If FGP_LOCK or FGP_CREAT are specified then the function may sleep even
   if the GFP flags specified for FGP_CREAT are atomic.
   </para><para>

   If there is a page cache page, it is returned with an increased refcount.
</para>
</refsect1>
</refentry>

<refentry id="API-find-get-pages-contig">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_get_pages_contig</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_get_pages_contig</refname>
 <refpurpose>
     gang contiguous pagecache lookup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned <function>find_get_pages_contig </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>index</parameter></paramdef>
   <paramdef>unsigned int <parameter>nr_pages</parameter></paramdef>
   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     The address_space to search
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>index</parameter></term>
   <listitem>
    <para>
     The starting page index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_pages</parameter></term>
   <listitem>
    <para>
     The maximum number of pages
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     Where the resulting pages are placed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>find_get_pages_contig</function> works exactly like <function>find_get_pages</function>, except
   that the returned number of pages are guaranteed to be contiguous.
   </para><para>

   <function>find_get_pages_contig</function> returns the number of pages which were found.
</para>
</refsect1>
</refentry>

<refentry id="API-find-get-pages-tag">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_get_pages_tag</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_get_pages_tag</refname>
 <refpurpose>
     find and return pages that match <parameter>tag</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned <function>find_get_pages_tag </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t * <parameter>index</parameter></paramdef>
   <paramdef>int <parameter>tag</parameter></paramdef>
   <paramdef>unsigned int <parameter>nr_pages</parameter></paramdef>
   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the address_space to search
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>index</parameter></term>
   <listitem>
    <para>
     the starting page index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tag</parameter></term>
   <listitem>
    <para>
     the tag index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_pages</parameter></term>
   <listitem>
    <para>
     the maximum number of pages
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     where the resulting pages are placed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Like find_get_pages, except we only return pages which are tagged with
   <parameter>tag</parameter>.   We update <parameter>index</parameter> to index the next page for the traversal.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-file-read-iter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_file_read_iter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_file_read_iter</refname>
 <refpurpose>
     generic filesystem read routine
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>generic_file_read_iter </function></funcdef>
   <paramdef>struct kiocb * <parameter>iocb</parameter></paramdef>
   <paramdef>struct iov_iter * <parameter>iter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>iocb</parameter></term>
   <listitem>
    <para>
     kernel I/O control block
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>iter</parameter></term>
   <listitem>
    <para>
     destination for the data read
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the <quote><function>read_iter</function></quote> routine for all filesystems
   that can use the page cache directly.
</para>
</refsect1>
</refentry>

<refentry id="API-filemap-fault">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>filemap_fault</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>filemap_fault</refname>
 <refpurpose>
     read in file data for page fault handling
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>filemap_fault </function></funcdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>struct vm_fault * <parameter>vmf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     vma in which the fault was taken
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vmf</parameter></term>
   <listitem>
    <para>
     struct vm_fault containing details of the fault
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>filemap_fault</function> is invoked via the vma operations vector for a
   mapped memory region to read in file data during a page fault.
   </para><para>

   The goto's are kind of ugly, but this streamlines the normal case of having
   it in the page cache, and handles the special cases reasonably without
   having a lot of duplicated code.
   </para><para>

   vma-&gt;vm_mm-&gt;mmap_sem must be held on entry.
   </para><para>

   If our return value has VM_FAULT_RETRY set, it's because
   <function>lock_page_or_retry</function> returned 0.
   The mmap_sem has usually been released in this case.
   See <function>__lock_page_or_retry</function> for the exception.
   </para><para>

   If our return value does not have VM_FAULT_RETRY set, the mmap_sem
   has not been released.
   </para><para>

   We never return with VM_FAULT_RETRY and a bit from VM_FAULT_ERROR set.
</para>
</refsect1>
</refentry>

<refentry id="API-read-cache-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>read_cache_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>read_cache_page</refname>
 <refpurpose>
     read into page cache, fill it if needed
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>read_cache_page </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>index</parameter></paramdef>
   <paramdef>int (*<parameter>filler</parameter>)
     <funcparams>void *, struct page *</funcparams></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the page's address_space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>index</parameter></term>
   <listitem>
    <para>
     the page index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filler</parameter></term>
   <listitem>
    <para>
     function to perform the read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     first arg to filler(data, page) function, often left as NULL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Read into the page cache. If a page already exists, and <function>PageUptodate</function> is
   not set, try to fill the page and wait for it to become unlocked.
   </para><para>

   If the page does not get brought uptodate, return -EIO.
</para>
</refsect1>
</refentry>

<refentry id="API-read-cache-page-gfp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>read_cache_page_gfp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>read_cache_page_gfp</refname>
 <refpurpose>
     read into page cache, using specified page allocation flags.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>read_cache_page_gfp </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>index</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the page's address_space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>index</parameter></term>
   <listitem>
    <para>
     the page index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp</parameter></term>
   <listitem>
    <para>
     the page allocator flags to use if allocating
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the same as <quote>read_mapping_page(mapping, index, NULL)</quote>, but with
   any new page allocations done using the specified allocation flags.
   </para><para>

   If the page does not get brought uptodate, return -EIO.
</para>
</refsect1>
</refentry>

<refentry id="API---generic-file-write-iter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__generic_file_write_iter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__generic_file_write_iter</refname>
 <refpurpose>
     write data to a file
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>__generic_file_write_iter </function></funcdef>
   <paramdef>struct kiocb * <parameter>iocb</parameter></paramdef>
   <paramdef>struct iov_iter * <parameter>from</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>iocb</parameter></term>
   <listitem>
    <para>
     IO state structure (file, offset, etc.)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     iov_iter with data to write
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function does all the work needed for actually writing data to a
   file. It does all basic checks, removes SUID from the file, updates
   modification times and calls proper subroutines depending on whether we
   do direct IO or a standard buffered write.
   </para><para>

   It expects i_mutex to be grabbed unless we work on a block device or similar
   object which does not need locking at all.
   </para><para>

   This function does *not* take care of syncing data in case of O_SYNC write.
   A caller has to handle it. This is mainly due to the fact that we want to
   avoid syncing under i_mutex.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-file-write-iter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_file_write_iter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_file_write_iter</refname>
 <refpurpose>
     write data to a file
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>generic_file_write_iter </function></funcdef>
   <paramdef>struct kiocb * <parameter>iocb</parameter></paramdef>
   <paramdef>struct iov_iter * <parameter>from</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>iocb</parameter></term>
   <listitem>
    <para>
     IO state structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     iov_iter with data to write
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a wrapper around <function>__generic_file_write_iter</function> to be used by most
   filesystems. It takes care of syncing the file in case of O_SYNC file
   and acquires i_mutex as needed.
</para>
</refsect1>
</refentry>

<refentry id="API-try-to-release-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>try_to_release_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>try_to_release_page</refname>
 <refpurpose>
     release old fs-specific metadata on a page
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>try_to_release_page </function></funcdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     the page which the kernel is trying to free
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation flags (and I/O mode)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The address_space is to try to release any data against the page
   (presumably at page-&gt;private).  If the release was successful, return `1'.
   Otherwise return zero.
   </para><para>

   This may also be called if PG_fscache is set on a page, indicating that the
   page is known to the local caching routines.
   </para><para>

   The <parameter>gfp_mask</parameter> argument specifies whether I/O may be performed to release
   this page (__GFP_IO), and whether the call may block (__GFP_WAIT &amp; __GFP_FS).
</para>
</refsect1>
</refentry>

<!-- mm/memory.c -->
<refentry id="API-zap-vma-ptes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>zap_vma_ptes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>zap_vma_ptes</refname>
 <refpurpose>
  remove ptes mapping the vma
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>zap_vma_ptes </function></funcdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>unsigned long <parameter>address</parameter></paramdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     vm_area_struct holding ptes to be zapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>address</parameter></term>
   <listitem>
    <para>
     starting address of pages to zap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     number of bytes to zap
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function only unmaps ptes assigned to VM_PFNMAP vmas.
   </para><para>

   The entire address range must be fully contained within the vma.
   </para><para>

   Returns 0 if successful.
</para>
</refsect1>
</refentry>

<refentry id="API-vm-insert-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vm_insert_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vm_insert_page</refname>
 <refpurpose>
     insert single page into user vma
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vm_insert_page </function></funcdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>unsigned long <parameter>addr</parameter></paramdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     user vma to map to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     target user address of this page
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     source kernel page
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This allows drivers to insert individual pages they've allocated
   into a user vma.
   </para><para>

   The page has to be a nice clean _individual_ kernel allocation.
   If you allocate a compound page, you need to have marked it as
   such (__GFP_COMP), or manually just split the page up yourself
   (see <function>split_page</function>).
   </para><para>

   NOTE! Traditionally this was done with <quote><function>remap_pfn_range</function></quote> which
   took an arbitrary page protection parameter. This doesn't allow
   that. Your vma protection will have to be set up correctly, which
   means that if you want a shared writable mapping, you'd better
   ask for a shared writable mapping!
   </para><para>

   The page does not need to be reserved.
   </para><para>

   Usually this function is called from f_op-&gt;<function>mmap</function> handler
   under mm-&gt;mmap_sem write-lock, so it can change vma-&gt;vm_flags.
   Caller must set VM_MIXEDMAP on vma if it wants to call this
   function from other places, for example from page-fault handler.
</para>
</refsect1>
</refentry>

<refentry id="API-vm-insert-pfn">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vm_insert_pfn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vm_insert_pfn</refname>
 <refpurpose>
     insert single pfn into user vma
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vm_insert_pfn </function></funcdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>unsigned long <parameter>addr</parameter></paramdef>
   <paramdef>unsigned long <parameter>pfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     user vma to map to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     target user address of this page
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pfn</parameter></term>
   <listitem>
    <para>
     source kernel pfn
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Similar to vm_insert_page, this allows drivers to insert individual pages
   they've allocated into a user vma. Same comments apply.
   </para><para>

   This function should only be called from a vm_ops-&gt;fault handler, and
   in that case the handler should return NULL.
   </para><para>

   vma cannot be a COW mapping.
   </para><para>

   As this is called only for pages that do not currently exist, we
   do not need to flush old virtual caches or the TLB.
</para>
</refsect1>
</refentry>

<refentry id="API-remap-pfn-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>remap_pfn_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>remap_pfn_range</refname>
 <refpurpose>
     remap kernel memory to userspace
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>remap_pfn_range </function></funcdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>unsigned long <parameter>addr</parameter></paramdef>
   <paramdef>unsigned long <parameter>pfn</parameter></paramdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
   <paramdef>pgprot_t <parameter>prot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     user vma to map to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     target user address to start at
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pfn</parameter></term>
   <listitem>
    <para>
     physical address of kernel memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of map area
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prot</parameter></term>
   <listitem>
    <para>
     page protection flags for this mapping
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   this is only safe if the mm semaphore is held when called.
</para>
</refsect1>
</refentry>

<refentry id="API-vm-iomap-memory">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vm_iomap_memory</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vm_iomap_memory</refname>
 <refpurpose>
     remap memory to userspace
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vm_iomap_memory </function></funcdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>phys_addr_t <parameter>start</parameter></paramdef>
   <paramdef>unsigned long <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     user vma to map to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     start of area
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     size of area
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a simplified <function>io_remap_pfn_range</function> for common driver use. The
   driver just needs to give us the physical memory range to be mapped,
   we'll figure out the rest from the vma information.
   </para><para>

   NOTE! Some drivers might want to tweak vma-&gt;vm_page_prot first to get
   whatever write-combining details or similar.
</para>
</refsect1>
</refentry>

<refentry id="API-unmap-mapping-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unmap_mapping_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unmap_mapping_range</refname>
 <refpurpose>
     unmap the portion of all mmaps in the specified address_space corresponding to the specified page range in the underlying file.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unmap_mapping_range </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>loff_t const <parameter>holebegin</parameter></paramdef>
   <paramdef>loff_t const <parameter>holelen</parameter></paramdef>
   <paramdef>int <parameter>even_cows</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the address space containing mmaps to be unmapped.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>holebegin</parameter></term>
   <listitem>
    <para>
     byte in first page to unmap, relative to the start of
     the underlying file.  This will be rounded down to a PAGE_SIZE
     boundary.  Note that this is different from <function>truncate_pagecache</function>, which
     must keep the partial page.  In contrast, we must get rid of
     partial pages.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>holelen</parameter></term>
   <listitem>
    <para>
     size of prospective hole in bytes.  This will be rounded
     up to a PAGE_SIZE boundary.  A holelen of zero truncates to the
     end of the file.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>even_cows</parameter></term>
   <listitem>
    <para>
     1 when truncating a file, unmap even private COWed pages;
     but 0 when invalidating pagecache, don't throw away private data.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-follow-pfn">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>follow_pfn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>follow_pfn</refname>
 <refpurpose>
     look up PFN at a user virtual address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>follow_pfn </function></funcdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>unsigned long <parameter>address</parameter></paramdef>
   <paramdef>unsigned long * <parameter>pfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     memory mapping
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>address</parameter></term>
   <listitem>
    <para>
     user virtual address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pfn</parameter></term>
   <listitem>
    <para>
     location to store found PFN
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Only IO mappings and raw PFN mappings are allowed.
   </para><para>

   Returns zero and the pfn at <parameter>pfn</parameter> on success, -ve otherwise.
</para>
</refsect1>
</refentry>

<!-- mm/vmalloc.c -->
<refentry id="API-vm-unmap-aliases">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vm_unmap_aliases</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vm_unmap_aliases</refname>
 <refpurpose>
  unmap outstanding lazy aliases in the vmap layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>vm_unmap_aliases </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 vmap/vmalloc layer lazily flushes kernel virtual mappings primarily
   to amortize TLB flushing overheads. What this means is that any page you
   have now, may, in a former life, have been mapped into kernel virtual
   address by the vmap layer and so there might be some CPUs with TLB entries
   still referencing that page (additional to the regular 1:1 kernel mapping).
   </para><para>

   vm_unmap_aliases flushes all such lazy mappings. After it returns, we can
   be sure that none of the pages we have control over will have any aliases
   from the vmap layer.
</para>
</refsect1>
</refentry>

<refentry id="API-vm-unmap-ram">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vm_unmap_ram</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vm_unmap_ram</refname>
 <refpurpose>
     unmap linear kernel address space set up by vm_map_ram
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>vm_unmap_ram </function></funcdef>
   <paramdef>const void * <parameter>mem</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mem</parameter></term>
   <listitem>
    <para>
     the pointer returned by vm_map_ram
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the count passed to that vm_map_ram call (cannot unmap partial)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-vm-map-ram">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vm_map_ram</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vm_map_ram</refname>
 <refpurpose>
     map pages linearly into kernel virtual address (vmalloc space)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>vm_map_ram </function></funcdef>
   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
   <paramdef>int <parameter>node</parameter></paramdef>
   <paramdef>pgprot_t <parameter>prot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     an array of pointers to the pages to be mapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of pages
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     prefer to allocate data structures on this node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prot</parameter></term>
   <listitem>
    <para>
     memory protection to use. PAGE_KERNEL for regular RAM
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If you use this function for less than VMAP_MAX_ALLOC pages, it could be
   faster than vmap so it's good.  But if you mix long-life and short-life
   objects with <function>vm_map_ram</function>, it could consume lots of address space through
   fragmentation (especially on a 32bit machine).  You could see failures in
   the end.  Please use this function for short-lived objects.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   a pointer to the address that has been mapped, or <constant>NULL</constant> on failure
</para>
</refsect1>
</refentry>

<refentry id="API-unmap-kernel-range-noflush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unmap_kernel_range_noflush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unmap_kernel_range_noflush</refname>
 <refpurpose>
     unmap kernel VM area
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unmap_kernel_range_noflush </function></funcdef>
   <paramdef>unsigned long <parameter>addr</parameter></paramdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     start of the VM area to unmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the VM area to unmap
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unmap PFN_UP(<parameter>size</parameter>) pages at <parameter>addr</parameter>.  The VM area <parameter>addr</parameter> and <parameter>size</parameter>
   specify should have been allocated using <function>get_vm_area</function> and its
   friends.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   This function does NOT do any cache flushing.  The caller is
   responsible for calling <function>flush_cache_vunmap</function> on to-be-mapped areas
   before calling this function and <function>flush_tlb_kernel_range</function> after.
</para>
</refsect1>
</refentry>

<refentry id="API-unmap-kernel-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unmap_kernel_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unmap_kernel_range</refname>
 <refpurpose>
     unmap kernel VM area and flush cache and TLB
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unmap_kernel_range </function></funcdef>
   <paramdef>unsigned long <parameter>addr</parameter></paramdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     start of the VM area to unmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the VM area to unmap
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Similar to <function>unmap_kernel_range_noflush</function> but flushes vcache before
   the unmapping and tlb after.
</para>
</refsect1>
</refentry>

<refentry id="API-vfree">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vfree</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vfree</refname>
 <refpurpose>
     release memory allocated by <function>vmalloc</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>vfree </function></funcdef>
   <paramdef>const void * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     memory base address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free the virtually continuous memory area starting at <parameter>addr</parameter>, as
   obtained from <function>vmalloc</function>, <function>vmalloc_32</function> or <function>__vmalloc</function>. If <parameter>addr</parameter> is
   NULL, no operation is performed.
   </para><para>

   Must not be called in NMI context (strictly speaking, only if we don't
   have CONFIG_ARCH_HAVE_NMI_SAFE_CMPXCHG, but making the calling
   conventions for <function>vfree</function> arch-depenedent would be a really bad idea)
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   assumes that the object at *addr has a size &gt;= sizeof(llist_node)
</para>
</refsect1>
</refentry>

<refentry id="API-vunmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vunmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vunmap</refname>
 <refpurpose>
     release virtual mapping obtained by <function>vmap</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>vunmap </function></funcdef>
   <paramdef>const void * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     memory base address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free the virtually contiguous memory area starting at <parameter>addr</parameter>,
   which was created from the page array passed to <function>vmap</function>.
   </para><para>

   Must not be called in interrupt context.
</para>
</refsect1>
</refentry>

<refentry id="API-vmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vmap</refname>
 <refpurpose>
     map an array of pages into virtually contiguous space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>vmap </function></funcdef>
   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
   <paramdef>unsigned long <parameter>flags</parameter></paramdef>
   <paramdef>pgprot_t <parameter>prot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     array of page pointers
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of pages to map
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     vm_area-&gt;flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prot</parameter></term>
   <listitem>
    <para>
     page protection for the mapping
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Maps <parameter>count</parameter> pages from <parameter>pages</parameter> into contiguous kernel virtual
   space.
</para>
</refsect1>
</refentry>

<refentry id="API-vmalloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmalloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vmalloc</refname>
 <refpurpose>
     allocate virtually contiguous memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>vmalloc </function></funcdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     allocation size
     Allocate enough pages to cover <parameter>size</parameter> from the page level
     allocator and map them into contiguous kernel virtual space.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   For tight control over page level allocator and protection flags
   use <function>__vmalloc</function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-vzalloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vzalloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vzalloc</refname>
 <refpurpose>
     allocate virtually contiguous memory with zero fill
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>vzalloc </function></funcdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     allocation size
     Allocate enough pages to cover <parameter>size</parameter> from the page level
     allocator and map them into contiguous kernel virtual space.
     The memory allocated is set to zero.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   For tight control over page level allocator and protection flags
   use <function>__vmalloc</function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-vmalloc-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmalloc_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vmalloc_user</refname>
 <refpurpose>
     allocate zeroed virtually contiguous memory for userspace
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>vmalloc_user </function></funcdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     allocation size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The resulting memory area is zeroed so it can be mapped to userspace
   without leaking data.
</para>
</refsect1>
</refentry>

<refentry id="API-vmalloc-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmalloc_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vmalloc_node</refname>
 <refpurpose>
     allocate memory on a specific node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>vmalloc_node </function></funcdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
   <paramdef>int <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     allocation size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     numa node
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate enough pages to cover <parameter>size</parameter> from the page level
   allocator and map them into contiguous kernel virtual space.
   </para><para>

   For tight control over page level allocator and protection flags
   use <function>__vmalloc</function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-vzalloc-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vzalloc_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vzalloc_node</refname>
 <refpurpose>
     allocate memory on a specific node with zero fill
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>vzalloc_node </function></funcdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
   <paramdef>int <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     allocation size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     numa node
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate enough pages to cover <parameter>size</parameter> from the page level
   allocator and map them into contiguous kernel virtual space.
   The memory allocated is set to zero.
   </para><para>

   For tight control over page level allocator and protection flags
   use <function>__vmalloc_node</function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-vmalloc-32">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmalloc_32</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vmalloc_32</refname>
 <refpurpose>
     allocate virtually contiguous memory (32bit addressable)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>vmalloc_32 </function></funcdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     allocation size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate enough 32bit PA addressable pages to cover <parameter>size</parameter> from the
   page level allocator and map them into contiguous kernel virtual space.
</para>
</refsect1>
</refentry>

<refentry id="API-vmalloc-32-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmalloc_32_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vmalloc_32_user</refname>
 <refpurpose>
     allocate zeroed virtually contiguous 32bit memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>vmalloc_32_user </function></funcdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     allocation size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The resulting memory area is 32bit addressable and zeroed so it can be
   mapped to userspace without leaking data.
</para>
</refsect1>
</refentry>

<refentry id="API-remap-vmalloc-range-partial">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>remap_vmalloc_range_partial</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>remap_vmalloc_range_partial</refname>
 <refpurpose>
     map vmalloc pages to userspace
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>remap_vmalloc_range_partial </function></funcdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>unsigned long <parameter>uaddr</parameter></paramdef>
   <paramdef>void * <parameter>kaddr</parameter></paramdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     vma to cover
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uaddr</parameter></term>
   <listitem>
    <para>
     target user address to start at
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kaddr</parameter></term>
   <listitem>
    <para>
     virtual address of vmalloc kernel memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of map area
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 for success, -Exxx on failure
   </para><para>

   This function checks that <parameter>kaddr</parameter> is a valid vmalloc'ed area,
   and that it is big enough to cover the range starting at
   <parameter>uaddr</parameter> in <parameter>vma</parameter>. Will return failure if that criteria isn't
   met.
   </para><para>

   Similar to <function>remap_pfn_range</function> (see mm/memory.c)
</para>
</refsect1>
</refentry>

<refentry id="API-remap-vmalloc-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>remap_vmalloc_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>remap_vmalloc_range</refname>
 <refpurpose>
     map vmalloc pages to userspace
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>remap_vmalloc_range </function></funcdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>void * <parameter>addr</parameter></paramdef>
   <paramdef>unsigned long <parameter>pgoff</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     vma to cover (map full range of vma)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     vmalloc memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pgoff</parameter></term>
   <listitem>
    <para>
     number of pages into addr before first page to map
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 for success, -Exxx on failure
   </para><para>

   This function checks that addr is a valid vmalloc'ed area, and
   that it is big enough to cover the vma. Will return failure if
   that criteria isn't met.
   </para><para>

   Similar to <function>remap_pfn_range</function> (see mm/memory.c)
</para>
</refsect1>
</refentry>

<refentry id="API-alloc-vm-area">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>alloc_vm_area</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>alloc_vm_area</refname>
 <refpurpose>
     allocate a range of kernel address space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct vm_struct * <function>alloc_vm_area </function></funcdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>pte_t ** <parameter>ptes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the area
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptes</parameter></term>
   <listitem>
    <para>
     returns the PTEs for the address space
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   NULL on failure, vm_struct on success
   </para><para>

   This function reserves a range of kernel address space, and
   allocates pagetables to map that range.  No actual mappings
   are created.
   </para><para>

   If <parameter>ptes</parameter> is non-NULL, pointers to the PTEs (in init_mm)
   allocated for the VM area are returned.
</para>
</refsect1>
</refentry>

<!-- mm/page_alloc.c -->
<refentry id="API-alloc-pages-exact-nid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>alloc_pages_exact_nid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>alloc_pages_exact_nid</refname>
 <refpurpose>
  allocate an exact number of physically-contiguous pages on a node.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>alloc_pages_exact_nid </function></funcdef>
   <paramdef>int <parameter>nid</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nid</parameter></term>
   <listitem>
    <para>
     the preferred node ID where memory should be allocated
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the number of bytes to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     GFP flags for the allocation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Like <function>alloc_pages_exact</function>, but try to allocate on node nid first before falling
   back.
   Note this is not <function>alloc_pages_exact_node</function> which allocates on a specific node,
   but is not exact.
</para>
</refsect1>
</refentry>

<refentry id="API-nr-free-zone-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>nr_free_zone_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>nr_free_zone_pages</refname>
 <refpurpose>
     count number of pages beyond high watermark
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>nr_free_zone_pages </function></funcdef>
   <paramdef>int <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     The zone index of the highest zone
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>nr_free_zone_pages</function> counts the number of counts pages which are beyond the
   high watermark within all zones at or below a given zone index.  For each
   zone, the number of pages is calculated as:
   managed_pages - high_pages
</para>
</refsect1>
</refentry>

<refentry id="API-nr-free-pagecache-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>nr_free_pagecache_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>nr_free_pagecache_pages</refname>
 <refpurpose>
     count number of pages beyond high watermark
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>nr_free_pagecache_pages </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>

   <function>nr_free_pagecache_pages</function> counts the number of pages which are beyond the
   high watermark within all zones.
</para>
</refsect1>
</refentry>

<refentry id="API-find-next-best-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_next_best_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_next_best_node</refname>
 <refpurpose>
     find the next node that should appear in a given node's fallback list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>find_next_best_node </function></funcdef>
   <paramdef>int <parameter>node</parameter></paramdef>
   <paramdef>nodemask_t * <parameter>used_node_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     node whose fallback list we're appending
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>used_node_mask</parameter></term>
   <listitem>
    <para>
     nodemask_t of already used nodes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   We use a number of factors to determine which is the next node that should
   appear on a given node's fallback list.  The node should not have appeared
   already in <parameter>node</parameter>'s fallback list, and it should be the next closest node
   according to the distance array (which contains arbitrary distance values
   from each node to each node in the system), and should also prefer nodes
   with no CPUs, since presumably they'll have very little allocation pressure
   on them otherwise.
   It returns -1 if no node is found.
</para>
</refsect1>
</refentry>

<refentry id="API-free-bootmem-with-active-regions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>free_bootmem_with_active_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>free_bootmem_with_active_regions</refname>
 <refpurpose>
     Call memblock_free_early_nid for each active range
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>free_bootmem_with_active_regions </function></funcdef>
   <paramdef>int <parameter>nid</parameter></paramdef>
   <paramdef>unsigned long <parameter>max_low_pfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nid</parameter></term>
   <listitem>
    <para>
     The node to free memory on. If MAX_NUMNODES, all nodes are freed.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_low_pfn</parameter></term>
   <listitem>
    <para>
     The highest PFN that will be passed to memblock_free_early_nid
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If an architecture guarantees that all ranges registered contain no holes
   and may be freed, this this function may be used instead of calling
   <function>memblock_free_early_nid</function> manually.
</para>
</refsect1>
</refentry>

<refentry id="API-sparse-memory-present-with-active-regions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sparse_memory_present_with_active_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sparse_memory_present_with_active_regions</refname>
 <refpurpose>
     Call memory_present for each active range
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sparse_memory_present_with_active_regions </function></funcdef>
   <paramdef>int <parameter>nid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nid</parameter></term>
   <listitem>
    <para>
     The node to call memory_present for. If MAX_NUMNODES, all nodes will be used.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If an architecture guarantees that all ranges registered contain no holes and may
   be freed, this function may be used instead of calling <function>memory_present</function> manually.
</para>
</refsect1>
</refentry>

<refentry id="API-get-pfn-range-for-nid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_pfn_range_for_nid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_pfn_range_for_nid</refname>
 <refpurpose>
     Return the start and end page frames for a node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>get_pfn_range_for_nid </function></funcdef>
   <paramdef>unsigned int <parameter>nid</parameter></paramdef>
   <paramdef>unsigned long * <parameter>start_pfn</parameter></paramdef>
   <paramdef>unsigned long * <parameter>end_pfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nid</parameter></term>
   <listitem>
    <para>
     The nid to return the range for. If MAX_NUMNODES, the min and max PFN are returned.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start_pfn</parameter></term>
   <listitem>
    <para>
     Passed by reference. On return, it will have the node start_pfn.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end_pfn</parameter></term>
   <listitem>
    <para>
     Passed by reference. On return, it will have the node end_pfn.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It returns the start and end page frame of a node based on information
   provided by <function>memblock_set_node</function>. If called for a node
   with no available memory, a warning is printed and the start and end
   PFNs will be 0.
</para>
</refsect1>
</refentry>

<refentry id="API-absent-pages-in-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>absent_pages_in_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>absent_pages_in_range</refname>
 <refpurpose>
     Return number of page frames in holes within a range
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>absent_pages_in_range </function></funcdef>
   <paramdef>unsigned long <parameter>start_pfn</parameter></paramdef>
   <paramdef>unsigned long <parameter>end_pfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>start_pfn</parameter></term>
   <listitem>
    <para>
     The start PFN to start searching for holes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end_pfn</parameter></term>
   <listitem>
    <para>
     The end PFN to stop searching for holes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It returns the number of pages frames in memory holes within a range.
</para>
</refsect1>
</refentry>

<refentry id="API-node-map-pfn-alignment">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>node_map_pfn_alignment</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>node_map_pfn_alignment</refname>
 <refpurpose>
     determine the maximum internode alignment
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>node_map_pfn_alignment </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 should be called after node map is populated and sorted.
   It calculates the maximum power of two alignment which can distinguish
   all the nodes.
   </para><para>

   For example, if all nodes are 1GiB and aligned to 1GiB, the return value
   would indicate 1GiB alignment with (1 &lt;&lt; (30 - PAGE_SHIFT)).  If the
   nodes are shifted by 256MiB, 256MiB.  Note that if only the last node is
   shifted, 1GiB is enough and this function will indicate so.
   </para><para>

   This is used to test whether pfn -&gt; nid mapping of the chosen memory
   model has fine enough granularity to avoid incorrect mapping for the
   populated node map.
   </para><para>

   Returns the determined alignment in pfn's.  0 if there is no alignment
   requirement (single node).
</para>
</refsect1>
</refentry>

<refentry id="API-find-min-pfn-with-active-regions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_min_pfn_with_active_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_min_pfn_with_active_regions</refname>
 <refpurpose>
     Find the minimum PFN registered
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>find_min_pfn_with_active_regions </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>

   It returns the minimum PFN based on information provided via
   <function>memblock_set_node</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-free-area-init-nodes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>free_area_init_nodes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>free_area_init_nodes</refname>
 <refpurpose>
     Initialise all pg_data_t and zone data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>free_area_init_nodes </function></funcdef>
   <paramdef>unsigned long * <parameter>max_zone_pfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>max_zone_pfn</parameter></term>
   <listitem>
    <para>
     an array of max PFNs for each zone
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This will call <function>free_area_init_node</function> for each active node in the system.
   Using the page ranges provided by <function>memblock_set_node</function>, the size of each
   zone in each node and their holes is calculated. If the maximum PFN
   between two adjacent zones match, it is assumed that the zone is empty.
   For example, if arch_max_dma_pfn == arch_max_dma32_pfn, it is assumed
   that arch_max_dma32_pfn has no pages. It is also assumed that a zone
   starts where the previous one ended. For example, ZONE_DMA32 starts
   at arch_max_dma_pfn.
</para>
</refsect1>
</refentry>

<refentry id="API-set-dma-reserve">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>set_dma_reserve</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>set_dma_reserve</refname>
 <refpurpose>
     set the specified number of pages reserved in the first zone
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>set_dma_reserve </function></funcdef>
   <paramdef>unsigned long <parameter>new_dma_reserve</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>new_dma_reserve</parameter></term>
   <listitem>
    <para>
     The number of pages to mark reserved
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The per-cpu batchsize and zone watermarks are determined by present_pages.
   In the DMA zone, a significant percentage may be consumed by kernel image
   and other unfreeable allocations which can skew the watermarks badly. This
   function may optionally be used to account for unfreeable pages in the
   first zone (e.g., ZONE_DMA). The effect will be lower watermarks and
   smaller per-cpu batchsize.
</para>
</refsect1>
</refentry>

<refentry id="API-setup-per-zone-wmarks">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>setup_per_zone_wmarks</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>setup_per_zone_wmarks</refname>
 <refpurpose>
     called when min_free_kbytes changes or when memory is hot-{added|removed}
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>setup_per_zone_wmarks </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>

   Ensures that the watermark[min,low,high] values for each zone are set
   correctly with respect to min_free_kbytes.
</para>
</refsect1>
</refentry>

<refentry id="API-get-pfnblock-flags-mask">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_pfnblock_flags_mask</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_pfnblock_flags_mask</refname>
 <refpurpose>
     Return the requested group of flags for the pageblock_nr_pages block of pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>get_pfnblock_flags_mask </function></funcdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
   <paramdef>unsigned long <parameter>pfn</parameter></paramdef>
   <paramdef>unsigned long <parameter>end_bitidx</parameter></paramdef>
   <paramdef>unsigned long <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     The page within the block of interest
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pfn</parameter></term>
   <listitem>
    <para>
     The target page frame number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end_bitidx</parameter></term>
   <listitem>
    <para>
     The last bit of interest to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     mask of bits that the caller is interested in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   pageblock_bits flags
</para>
</refsect1>
</refentry>

<refentry id="API-set-pfnblock-flags-mask">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>set_pfnblock_flags_mask</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>set_pfnblock_flags_mask</refname>
 <refpurpose>
     Set the requested group of flags for a pageblock_nr_pages block of pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>set_pfnblock_flags_mask </function></funcdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
   <paramdef>unsigned long <parameter>flags</parameter></paramdef>
   <paramdef>unsigned long <parameter>pfn</parameter></paramdef>
   <paramdef>unsigned long <parameter>end_bitidx</parameter></paramdef>
   <paramdef>unsigned long <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     The page within the block of interest
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     The flags to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pfn</parameter></term>
   <listitem>
    <para>
     The target page frame number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end_bitidx</parameter></term>
   <listitem>
    <para>
     The last bit of interest
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     mask of bits that the caller is interested in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-alloc-contig-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>alloc_contig_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>alloc_contig_range</refname>
 <refpurpose>
     - tries to allocate given range of pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>alloc_contig_range </function></funcdef>
   <paramdef>unsigned long <parameter>start</parameter></paramdef>
   <paramdef>unsigned long <parameter>end</parameter></paramdef>
   <paramdef>unsigned <parameter>migratetype</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     start PFN to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     one-past-the-last PFN to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>migratetype</parameter></term>
   <listitem>
    <para>
     migratetype of the underlaying pageblocks (either
     #MIGRATE_MOVABLE or #MIGRATE_CMA).  All pageblocks
     in range must have the same migratetype and it must
     be either of the two.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The PFN range does not have to be pageblock or MAX_ORDER_NR_PAGES
   aligned, however it's the caller's responsibility to guarantee that
   we are the only thread that changes migrate type of pageblocks the
   pages fall in.
   </para><para>

   The PFN range must belong to a single zone.
   </para><para>

   Returns zero on success or negative error code.  On success all
   pages which PFN is in [start, end) are allocated for the caller and
   need to be freed with <function>free_contig_range</function>.
</para>
</refsect1>
</refentry>

<!-- mm/mempool.c -->
<refentry id="API-mempool-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mempool_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mempool_destroy</refname>
 <refpurpose>
  deallocate a memory pool
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mempool_destroy </function></funcdef>
   <paramdef>mempool_t * <parameter>pool</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pool</parameter></term>
   <listitem>
    <para>
     pointer to the memory pool which was allocated via
     <function>mempool_create</function>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free all reserved elements in <parameter>pool</parameter> and <parameter>pool</parameter> itself.  This function
   only sleeps if the <function>free_fn</function> function sleeps.
</para>
</refsect1>
</refentry>

<refentry id="API-mempool-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mempool_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mempool_create</refname>
 <refpurpose>
     create a memory pool
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>mempool_t * <function>mempool_create </function></funcdef>
   <paramdef>int <parameter>min_nr</parameter></paramdef>
   <paramdef>mempool_alloc_t * <parameter>alloc_fn</parameter></paramdef>
   <paramdef>mempool_free_t * <parameter>free_fn</parameter></paramdef>
   <paramdef>void * <parameter>pool_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>min_nr</parameter></term>
   <listitem>
    <para>
     the minimum number of elements guaranteed to be
     allocated for this pool.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alloc_fn</parameter></term>
   <listitem>
    <para>
     user-defined element-allocation function.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>free_fn</parameter></term>
   <listitem>
    <para>
     user-defined element-freeing function.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pool_data</parameter></term>
   <listitem>
    <para>
     optional private data available to the user-defined functions.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   this function creates and allocates a guaranteed size, preallocated
   memory pool. The pool can be used from the <function>mempool_alloc</function> and <function>mempool_free</function>
   functions. This function might sleep. Both the <function>alloc_fn</function> and the <function>free_fn</function>
   functions might sleep - as long as the <function>mempool_alloc</function> function is not called
   from IRQ contexts.
</para>
</refsect1>
</refentry>

<refentry id="API-mempool-resize">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mempool_resize</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mempool_resize</refname>
 <refpurpose>
     resize an existing memory pool
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mempool_resize </function></funcdef>
   <paramdef>mempool_t * <parameter>pool</parameter></paramdef>
   <paramdef>int <parameter>new_min_nr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pool</parameter></term>
   <listitem>
    <para>
     pointer to the memory pool which was allocated via
     <function>mempool_create</function>.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_min_nr</parameter></term>
   <listitem>
    <para>
     the new minimum number of elements guaranteed to be
     allocated for this pool.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function shrinks/grows the pool. In the case of growing,
   it cannot be guaranteed that the pool will be grown to the new
   size immediately, but new <function>mempool_free</function> calls will refill it.
   This function may sleep.
   </para><para>

   Note, the caller must guarantee that no mempool_destroy is called
   while this function is running. <function>mempool_alloc</function> &amp; <function>mempool_free</function>
   might be called (eg. from IRQ contexts) while this function executes.
</para>
</refsect1>
</refentry>

<refentry id="API-mempool-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mempool_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mempool_alloc</refname>
 <refpurpose>
     allocate an element from a specific memory pool
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>mempool_alloc </function></funcdef>
   <paramdef>mempool_t * <parameter>pool</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pool</parameter></term>
   <listitem>
    <para>
     pointer to the memory pool which was allocated via
     <function>mempool_create</function>.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     the usual allocation bitmask.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   this function only sleeps if the <function>alloc_fn</function> function sleeps or
   returns NULL. Note that due to preallocation, this function
   *never* fails when called from process contexts. (it might
   fail if called from an IRQ context.)
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   using __GFP_ZERO is not supported.
</para>
</refsect1>
</refentry>

<refentry id="API-mempool-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mempool_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mempool_free</refname>
 <refpurpose>
     return an element to the pool.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mempool_free </function></funcdef>
   <paramdef>void * <parameter>element</parameter></paramdef>
   <paramdef>mempool_t * <parameter>pool</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>element</parameter></term>
   <listitem>
    <para>
     pool element pointer.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pool</parameter></term>
   <listitem>
    <para>
     pointer to the memory pool which was allocated via
     <function>mempool_create</function>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   this function only sleeps if the <function>free_fn</function> function sleeps.
</para>
</refsect1>
</refentry>

<!-- mm/dmapool.c -->
<refentry id="API-dma-pool-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_pool_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_pool_create</refname>
 <refpurpose>
  Creates a pool of consistent memory blocks, for dma.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct dma_pool * <function>dma_pool_create </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>size_t <parameter>align</parameter></paramdef>
   <paramdef>size_t <parameter>boundary</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of pool, for diagnostics
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device that will be doing the DMA
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the blocks in this pool.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>align</parameter></term>
   <listitem>
    <para>
     alignment requirement for blocks; must be a power of two
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>boundary</parameter></term>
   <listitem>
    <para>
     returned blocks won't cross this power of two boundary
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   !<function>in_interrupt</function>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a dma allocation pool with the requested characteristics, or
   null if one can't be created.  Given one of these pools, <function>dma_pool_alloc</function>
   may be used to allocate memory.  Such memory will all have <quote>consistent</quote>
   DMA mappings, accessible by the device and its driver without using
   cache flushing primitives.  The actual size of blocks allocated may be
   larger than requested because of alignment.
   </para><para>

   If <parameter>boundary</parameter> is nonzero, objects returned from <function>dma_pool_alloc</function> won't
   cross that size boundary.  This is useful for devices which have
   addressing restrictions on individual DMA transfers, such as not crossing
   boundaries of 4KBytes.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-pool-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_pool_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_pool_destroy</refname>
 <refpurpose>
     destroys a pool of dma memory blocks.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dma_pool_destroy </function></funcdef>
   <paramdef>struct dma_pool * <parameter>pool</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pool</parameter></term>
   <listitem>
    <para>
     dma pool that will be destroyed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   !<function>in_interrupt</function>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Caller guarantees that no more memory from the pool is in use,
   and that nothing will try to use the pool after this call.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-pool-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_pool_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_pool_alloc</refname>
 <refpurpose>
     get a block of consistent memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>dma_pool_alloc </function></funcdef>
   <paramdef>struct dma_pool * <parameter>pool</parameter></paramdef>
   <paramdef>gfp_t <parameter>mem_flags</parameter></paramdef>
   <paramdef>dma_addr_t * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pool</parameter></term>
   <listitem>
    <para>
     dma pool that will produce the block
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mem_flags</parameter></term>
   <listitem>
    <para>
     GFP_* bitmask
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     pointer to dma address of block
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns the kernel virtual address of a currently unused block,
   and reports its dma address through the handle.
   If such a memory block can't be allocated, <constant>NULL</constant> is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-pool-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_pool_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dma_pool_free</refname>
 <refpurpose>
     put block back into dma pool
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dma_pool_free </function></funcdef>
   <paramdef>struct dma_pool * <parameter>pool</parameter></paramdef>
   <paramdef>void * <parameter>vaddr</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>dma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pool</parameter></term>
   <listitem>
    <para>
     the dma pool holding the block
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vaddr</parameter></term>
   <listitem>
    <para>
     virtual address of block
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma</parameter></term>
   <listitem>
    <para>
     dma address of block
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Caller promises neither device nor driver will again touch this block
   unless it is first re-allocated.
</para>
</refsect1>
</refentry>

<refentry id="API-dmam-pool-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmam_pool_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmam_pool_create</refname>
 <refpurpose>
     Managed <function>dma_pool_create</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct dma_pool * <function>dmam_pool_create </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>size_t <parameter>align</parameter></paramdef>
   <paramdef>size_t <parameter>allocation</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of pool, for diagnostics
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device that will be doing the DMA
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the blocks in this pool.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>align</parameter></term>
   <listitem>
    <para>
     alignment requirement for blocks; must be a power of two
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>allocation</parameter></term>
   <listitem>
    <para>
     returned blocks won't cross this boundary (or zero)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Managed <function>dma_pool_create</function>.  DMA pool created with this function is
   automatically destroyed on driver detach.
</para>
</refsect1>
</refentry>

<refentry id="API-dmam-pool-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmam_pool_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmam_pool_destroy</refname>
 <refpurpose>
     Managed <function>dma_pool_destroy</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dmam_pool_destroy </function></funcdef>
   <paramdef>struct dma_pool * <parameter>pool</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pool</parameter></term>
   <listitem>
    <para>
     dma pool that will be destroyed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Managed <function>dma_pool_destroy</function>.
</para>
</refsect1>
</refentry>

<!-- mm/page-writeback.c -->
<refentry id="API-balance-dirty-pages-ratelimited">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>balance_dirty_pages_ratelimited</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>balance_dirty_pages_ratelimited</refname>
 <refpurpose>
  balance dirty memory state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>balance_dirty_pages_ratelimited </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     address_space which was dirtied
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Processes which are dirtying memory should call in here once for each page
   which was newly dirtied.  The function will periodically check the system's
   dirty state and will initiate writeback if needed.
   </para><para>

   On really big machines, get_writeback_state is expensive, so try to avoid
   calling it too often (ratelimiting).  But once we're over the dirty memory
   limit we decrease the ratelimiting by a lot, to prevent individual processes
   from overshooting the limit by (ratelimit_pages) each.
</para>
</refsect1>
</refentry>

<refentry id="API-tag-pages-for-writeback">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>tag_pages_for_writeback</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>tag_pages_for_writeback</refname>
 <refpurpose>
     tag pages to be written by write_cache_pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>tag_pages_for_writeback </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>start</parameter></paramdef>
   <paramdef>pgoff_t <parameter>end</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     address space structure to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     starting page index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     ending page index (inclusive)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function scans the page range from <parameter>start</parameter> to <parameter>end</parameter> (inclusive) and tags
   all pages that have DIRTY tag set with a special TOWRITE tag. The idea is
   that write_cache_pages (or whoever calls this function) will then use
   TOWRITE tag to identify pages eligible for writeback.  This mechanism is
   used to avoid livelocking of writeback by a process steadily creating new
   dirty pages in the file (thus it is important for this function to be quick
   so that it can tag pages faster than a dirtying process can create them).
</para>
</refsect1>
</refentry>

<refentry id="API-write-cache-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>write_cache_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>write_cache_pages</refname>
 <refpurpose>
     walk the list of dirty pages of the given address space and write all of them.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>write_cache_pages </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>struct writeback_control * <parameter>wbc</parameter></paramdef>
   <paramdef>writepage_t <parameter>writepage</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     address space structure to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wbc</parameter></term>
   <listitem>
    <para>
     subtract the number of written pages from *<parameter>wbc</parameter>-&gt;nr_to_write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>writepage</parameter></term>
   <listitem>
    <para>
     function called for each page
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data passed to writepage function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a page is already under I/O, <function>write_cache_pages</function> skips it, even
   if it's dirty.  This is desirable behaviour for memory-cleaning writeback,
   but it is INCORRECT for data-integrity system calls such as <function>fsync</function>.  <function>fsync</function>
   and <function>msync</function> need to guarantee that all the data which was dirty at the time
   the call was made get new I/O started against them.  If wbc-&gt;sync_mode is
   WB_SYNC_ALL then we were called for data integrity and we must wait for
   existing IO to complete.
   </para><para>

   To avoid livelocks (when other process dirties new pages), we first tag
   pages which should be written back with TOWRITE tag and only then start
   writing them. For data-integrity sync we have to be careful so that we do
   not miss some pages (e.g., because some other process has cleared TOWRITE
   tag we set). The rule we follow is that TOWRITE tag can be cleared only
   by the process clearing the DIRTY tag (and submitting the page for IO).
</para>
</refsect1>
</refentry>

<refentry id="API-generic-writepages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_writepages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_writepages</refname>
 <refpurpose>
     walk the list of dirty pages of the given address space and <function>writepage</function> all of them.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>generic_writepages </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>struct writeback_control * <parameter>wbc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     address space structure to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wbc</parameter></term>
   <listitem>
    <para>
     subtract the number of written pages from *<parameter>wbc</parameter>-&gt;nr_to_write
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a library function, which implements the <function>writepages</function>
   address_space_operation.
</para>
</refsect1>
</refentry>

<refentry id="API-write-one-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>write_one_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>write_one_page</refname>
 <refpurpose>
     write out a single page and optionally wait on I/O
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>write_one_page </function></funcdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
   <paramdef>int <parameter>wait</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     the page to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wait</parameter></term>
   <listitem>
    <para>
     if true, wait on writeout
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The page must be locked by the caller and will be unlocked upon return.
   </para><para>

   <function>write_one_page</function> returns a negative error code if I/O failed.
</para>
</refsect1>
</refentry>

<refentry id="API-wait-for-stable-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wait_for_stable_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wait_for_stable_page</refname>
 <refpurpose>
     wait for writeback to finish, if necessary.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>wait_for_stable_page </function></funcdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     The page to wait on.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function determines if the given page is related to a backing device
   that requires page contents to be held stable during writeback.  If so, then
   it will wait for any pending writeback to complete.
</para>
</refsect1>
</refentry>

<!-- mm/truncate.c -->
<refentry id="API-truncate-inode-pages-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>truncate_inode_pages_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>truncate_inode_pages_range</refname>
 <refpurpose>
  truncate range of pages specified by start &amp; end byte offsets
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>truncate_inode_pages_range </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>loff_t <parameter>lstart</parameter></paramdef>
   <paramdef>loff_t <parameter>lend</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     mapping to truncate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lstart</parameter></term>
   <listitem>
    <para>
     offset from which to truncate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lend</parameter></term>
   <listitem>
    <para>
     offset to which to truncate (inclusive)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Truncate the page cache, removing the pages that are between
   specified offsets (and zeroing out partial pages
   if lstart or lend + 1 is not page aligned).
   </para><para>

   Truncate takes two passes - the first pass is nonblocking.  It will not
   block on page locks and it will not block on writeback.  The second pass
   will wait.  This is to prevent as much IO as possible in the affected region.
   The first pass will remove most pages, so the search cost of the second pass
   is low.
   </para><para>

   We pass down the cache-hot hint to the page freeing code.  Even if the
   mapping is large, it is probably the case that the final pages are the most
   recently touched, and freeing happens in ascending file offset order.
   </para><para>

   Note that since -&gt;<function>invalidatepage</function> accepts range to invalidate
   truncate_inode_pages_range is able to handle cases where lend + 1 is not
   page aligned properly.
</para>
</refsect1>
</refentry>

<refentry id="API-truncate-inode-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>truncate_inode_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>truncate_inode_pages</refname>
 <refpurpose>
     truncate *all* the pages from an offset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>truncate_inode_pages </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>loff_t <parameter>lstart</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     mapping to truncate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lstart</parameter></term>
   <listitem>
    <para>
     offset from which to truncate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called under (and serialised by) inode-&gt;i_mutex.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   When this function returns, there can be a page in the process of
   deletion (inside <function>__delete_from_page_cache</function>) in the specified range.  Thus
   mapping-&gt;nrpages can be non-zero when this function returns even after
   truncation of the whole mapping.
</para>
</refsect1>
</refentry>

<refentry id="API-truncate-inode-pages-final">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>truncate_inode_pages_final</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>truncate_inode_pages_final</refname>
 <refpurpose>
     truncate *all* pages before inode dies
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>truncate_inode_pages_final </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     mapping to truncate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called under (and serialized by) inode-&gt;i_mutex.
   </para><para>

   Filesystems have to use this in the .evict_inode path to inform the
   VM that this is the final truncate and the inode is going away.
</para>
</refsect1>
</refentry>

<refentry id="API-invalidate-mapping-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>invalidate_mapping_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>invalidate_mapping_pages</refname>
 <refpurpose>
     Invalidate all the unlocked pages of one inode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>invalidate_mapping_pages </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>start</parameter></paramdef>
   <paramdef>pgoff_t <parameter>end</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the address_space which holds the pages to invalidate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     the offset 'from' which to invalidate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     the offset 'to' which to invalidate (inclusive)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function only removes the unlocked pages, if you want to
   remove all the pages of one inode, you must call truncate_inode_pages.
   </para><para>

   <function>invalidate_mapping_pages</function> will not block on IO activity. It will not
   invalidate pages which are dirty, locked, under writeback or mapped into
   pagetables.
</para>
</refsect1>
</refentry>

<refentry id="API-invalidate-inode-pages2-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>invalidate_inode_pages2_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>invalidate_inode_pages2_range</refname>
 <refpurpose>
     remove range of pages from an address_space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>invalidate_inode_pages2_range </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>pgoff_t <parameter>start</parameter></paramdef>
   <paramdef>pgoff_t <parameter>end</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the address_space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     the page offset 'from' which to invalidate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     the page offset 'to' which to invalidate (inclusive)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Any pages which are found to be mapped into pagetables are unmapped prior to
   invalidation.
   </para><para>

   Returns -EBUSY if any pages could not be invalidated.
</para>
</refsect1>
</refentry>

<refentry id="API-invalidate-inode-pages2">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>invalidate_inode_pages2</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>invalidate_inode_pages2</refname>
 <refpurpose>
     remove all pages from an address_space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>invalidate_inode_pages2 </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     the address_space
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Any pages which are found to be mapped into pagetables are unmapped prior to
   invalidation.
   </para><para>

   Returns -EBUSY if any pages could not be invalidated.
</para>
</refsect1>
</refentry>

<refentry id="API-truncate-pagecache">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>truncate_pagecache</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>truncate_pagecache</refname>
 <refpurpose>
     unmap and remove pagecache that has been truncated
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>truncate_pagecache </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>loff_t <parameter>newsize</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     inode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>newsize</parameter></term>
   <listitem>
    <para>
     new file size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   inode's new i_size must already be written before truncate_pagecache
   is called.
   </para><para>

   This function should typically be called before the filesystem
   releases resources associated with the freed range (eg. deallocates
   blocks). This way, pagecache will always stay logically coherent
   with on-disk format, and the filesystem would not have to deal with
   situations such as writepage being called for a page that has already
   had its underlying blocks deallocated.
</para>
</refsect1>
</refentry>

<refentry id="API-truncate-setsize">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>truncate_setsize</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>truncate_setsize</refname>
 <refpurpose>
     update inode and pagecache for a new file size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>truncate_setsize </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>loff_t <parameter>newsize</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     inode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>newsize</parameter></term>
   <listitem>
    <para>
     new file size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   truncate_setsize updates i_size and performs pagecache truncation (if
   necessary) to <parameter>newsize</parameter>. It will be typically be called from the filesystem's
   setattr function when ATTR_SIZE is passed in.
   </para><para>

   Must be called with a lock serializing truncates and writes (generally
   i_mutex but e.g. xfs uses a different lock) and before all filesystem
   specific block truncation has been performed.
</para>
</refsect1>
</refentry>

<refentry id="API-pagecache-isize-extended">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pagecache_isize_extended</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pagecache_isize_extended</refname>
 <refpurpose>
     update pagecache after extension of i_size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pagecache_isize_extended </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>loff_t <parameter>from</parameter></paramdef>
   <paramdef>loff_t <parameter>to</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     inode for which i_size was extended
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     original inode size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     new inode size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Handle extension of inode size either caused by extending truncate or by
   write starting after current i_size. We mark the page straddling current
   i_size RO so that <function>page_mkwrite</function> is called on the nearest write access to
   the page.  This way filesystem can be sure that <function>page_mkwrite</function> is called on
   the page before user writes to the page via mmap after the i_size has been
   changed.
   </para><para>

   The function must be called after i_size is updated so that page fault
   coming after we unlock the page will already see the new i_size.
   The function must be called while we still hold i_mutex - this not only
   makes sure i_size is stable but also that userspace cannot observe new
   i_size value before we are prepared to store mmap writes at new inode size.
</para>
</refsect1>
</refentry>

<refentry id="API-truncate-pagecache-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>truncate_pagecache_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>truncate_pagecache_range</refname>
 <refpurpose>
     unmap and remove pagecache that is hole-punched
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>truncate_pagecache_range </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>loff_t <parameter>lstart</parameter></paramdef>
   <paramdef>loff_t <parameter>lend</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     inode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lstart</parameter></term>
   <listitem>
    <para>
     offset of beginning of hole
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lend</parameter></term>
   <listitem>
    <para>
     offset of last byte of hole
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should typically be called before the filesystem
   releases resources associated with the freed range (eg. deallocates
   blocks). This way, pagecache will always stay logically coherent
   with on-disk format, and the filesystem would not have to deal with
   situations such as writepage being called for a page that has already
   had its underlying blocks deallocated.
</para>
</refsect1>
</refentry>

     </sect1>
  </chapter>


  <chapter id="ipc">
     <title>Kernel IPC facilities</title>

     <sect1><title>IPC utilities</title>
<!-- ipc/util.c -->
<refentry id="API-ipc-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_init</refname>
 <refpurpose>
  initialise ipc subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ipc_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>

   The various sysv ipc resources (semaphores, messages and shared
   memory) are initialised.
   </para><para>

   A callback routine is registered into the memory hotplug notifier
</para>
</refsect1>
<refsect1>
<title>chain</title>
<para>
   since msgmni scales to lowmem this callback routine will be
   called upon successful memory add / remove to recompute msmgni.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-init-ids">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_init_ids</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_init_ids</refname>
 <refpurpose>
     initialise ipc identifiers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ipc_init_ids </function></funcdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc identifier set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set up the sequence range to use for the ipc identifier range (limited
   below IPCMNI) then initialise the ids idr.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-init-proc-interface">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_init_proc_interface</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_init_proc_interface</refname>
 <refpurpose>
     create a proc interface for sysipc types using a seq_file interface.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ipc_init_proc_interface </function></funcdef>
   <paramdef>const char * <parameter>path</parameter></paramdef>
   <paramdef>const char * <parameter>header</parameter></paramdef>
   <paramdef>int <parameter>ids</parameter></paramdef>
   <paramdef>int (*<parameter>show</parameter>)
     <funcparams>struct seq_file *, void *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>path</parameter></term>
   <listitem>
    <para>
     Path in procfs
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>header</parameter></term>
   <listitem>
    <para>
     Banner to be printed at the beginning of the file.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc id table to iterate.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>show</parameter></term>
   <listitem>
    <para>
     show routine.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-ipc-findkey">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_findkey</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_findkey</refname>
 <refpurpose>
     find a key in an ipc identifier set
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kern_ipc_perm * <function>ipc_findkey </function></funcdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
   <paramdef>key_t <parameter>key</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>key</parameter></term>
   <listitem>
    <para>
     key to find
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the locked pointer to the ipc structure if found or NULL
   otherwise. If key is found ipc points to the owning ipc structure
   </para><para>

   Called with ipc_ids.rwsem held.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-get-maxid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_get_maxid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_get_maxid</refname>
 <refpurpose>
     get the last assigned id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ipc_get_maxid </function></funcdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc identifier set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called with ipc_ids.rwsem held.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-addid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_addid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_addid</refname>
 <refpurpose>
     add an ipc identifier
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ipc_addid </function></funcdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
   <paramdef>struct kern_ipc_perm * <parameter>new</parameter></paramdef>
   <paramdef>int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     new ipc permission set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     limit for the number of used ids
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add an entry 'new' to the ipc ids idr. The permissions object is
   initialised and the first free entry is set up and the id assigned
   is returned. The 'new' entry is returned in a locked state on success.
   On failure the entry is not locked and a negative err-code is returned.
   </para><para>

   Called with writer ipc_ids.rwsem held.
</para>
</refsect1>
</refentry>

<refentry id="API-ipcget-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipcget_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipcget_new</refname>
 <refpurpose>
     create a new ipc object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ipcget_new </function></funcdef>
   <paramdef>struct ipc_namespace * <parameter>ns</parameter></paramdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
   <paramdef>const struct ipc_ops * <parameter>ops</parameter></paramdef>
   <paramdef>struct ipc_params * <parameter>params</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ns</parameter></term>
   <listitem>
    <para>
     ipc namespace
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     the actual creation routine to call
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     its parameters
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is called by sys_msgget, <function>sys_semget</function> and <function>sys_shmget</function>
   when the key is IPC_PRIVATE.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-check-perms">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_check_perms</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_check_perms</refname>
 <refpurpose>
     check security and permissions for an ipc object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ipc_check_perms </function></funcdef>
   <paramdef>struct ipc_namespace * <parameter>ns</parameter></paramdef>
   <paramdef>struct kern_ipc_perm * <parameter>ipcp</parameter></paramdef>
   <paramdef>const struct ipc_ops * <parameter>ops</parameter></paramdef>
   <paramdef>struct ipc_params * <parameter>params</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ns</parameter></term>
   <listitem>
    <para>
     ipc namespace
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ipcp</parameter></term>
   <listitem>
    <para>
     ipc permission set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     the actual security routine to call
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     its parameters
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is called by <function>sys_msgget</function>, <function>sys_semget</function> and <function>sys_shmget</function>
   when the key is not IPC_PRIVATE and that key already exists in the
   ds IDR.
   </para><para>

   On success, the ipc id is returned.
   </para><para>

   It is called with ipc_ids.rwsem and ipcp-&gt;lock held.
</para>
</refsect1>
</refentry>

<refentry id="API-ipcget-public">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipcget_public</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipcget_public</refname>
 <refpurpose>
     get an ipc object or create a new one
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ipcget_public </function></funcdef>
   <paramdef>struct ipc_namespace * <parameter>ns</parameter></paramdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
   <paramdef>const struct ipc_ops * <parameter>ops</parameter></paramdef>
   <paramdef>struct ipc_params * <parameter>params</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ns</parameter></term>
   <listitem>
    <para>
     ipc namespace
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     the actual creation routine to call
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     its parameters
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is called by sys_msgget, <function>sys_semget</function> and <function>sys_shmget</function>
   when the key is not IPC_PRIVATE.
   It adds a new entry if the key is not found and does some permission
   / security checkings if the key is found.
   </para><para>

   On success, the ipc id is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-rmid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_rmid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_rmid</refname>
 <refpurpose>
     remove an ipc identifier
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ipc_rmid </function></funcdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
   <paramdef>struct kern_ipc_perm * <parameter>ipcp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ipcp</parameter></term>
   <listitem>
    <para>
     ipc perm structure containing the identifier to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   ipc_ids.rwsem (as a writer) and the spinlock for this ID are held
   before this function is called, and remain locked on the exit.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_alloc</refname>
 <refpurpose>
     allocate ipc space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>ipc_alloc </function></funcdef>
   <paramdef>int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size desired
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate memory from the appropriate pools and return a pointer to it.
   NULL is returned if the allocation fails
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_free</refname>
 <refpurpose>
     free ipc space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ipc_free </function></funcdef>
   <paramdef>void * <parameter>ptr</parameter></paramdef>
   <paramdef>int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer returned by ipc_alloc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of block
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free a block created with <function>ipc_alloc</function>. The caller must know the size
   used in the allocation call.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-rcu-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_rcu_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_rcu_alloc</refname>
 <refpurpose>
     allocate ipc and rcu space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>ipc_rcu_alloc </function></funcdef>
   <paramdef>int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size desired
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate memory for the rcu header structure +  the object.
   Returns the pointer to the object or NULL upon failure.
</para>
</refsect1>
</refentry>

<refentry id="API-ipcperms">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipcperms</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipcperms</refname>
 <refpurpose>
     check ipc permissions
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ipcperms </function></funcdef>
   <paramdef>struct ipc_namespace * <parameter>ns</parameter></paramdef>
   <paramdef>struct kern_ipc_perm * <parameter>ipcp</parameter></paramdef>
   <paramdef>short <parameter>flag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ns</parameter></term>
   <listitem>
    <para>
     ipc namespace
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ipcp</parameter></term>
   <listitem>
    <para>
     ipc permission set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flag</parameter></term>
   <listitem>
    <para>
     desired permission set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check user, group, other permissions for access
   to ipc resources. return 0 if allowed
   </para><para>

   <parameter>flag</parameter> will most probably be 0 or S_...UGO from &lt;linux/stat.h&gt;
</para>
</refsect1>
</refentry>

<refentry id="API-kernel-to-ipc64-perm">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kernel_to_ipc64_perm</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kernel_to_ipc64_perm</refname>
 <refpurpose>
     convert kernel ipc permissions to user
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kernel_to_ipc64_perm </function></funcdef>
   <paramdef>struct kern_ipc_perm * <parameter>in</parameter></paramdef>
   <paramdef>struct ipc64_perm * <parameter>out</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>in</parameter></term>
   <listitem>
    <para>
     kernel permissions
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>out</parameter></term>
   <listitem>
    <para>
     new style ipc permissions
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Turn the kernel object <parameter>in</parameter> into a set of permissions descriptions
   for returning to userspace (<parameter>out</parameter>).
</para>
</refsect1>
</refentry>

<refentry id="API-ipc64-perm-to-ipc-perm">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc64_perm_to_ipc_perm</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc64_perm_to_ipc_perm</refname>
 <refpurpose>
     convert new ipc permissions to old
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ipc64_perm_to_ipc_perm </function></funcdef>
   <paramdef>struct ipc64_perm * <parameter>in</parameter></paramdef>
   <paramdef>struct ipc_perm * <parameter>out</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>in</parameter></term>
   <listitem>
    <para>
     new style ipc permissions
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>out</parameter></term>
   <listitem>
    <para>
     old style ipc permissions
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Turn the new style permissions object <parameter>in</parameter> into a compatibility
   object and store it into the <parameter>out</parameter> pointer.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-obtain-object">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_obtain_object</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_obtain_object</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kern_ipc_perm * <function>ipc_obtain_object </function></funcdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
   <paramdef>int <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     ipc id to look for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Look for an id in the ipc ids idr and return associated ipc object.
   </para><para>

   Call inside the RCU critical section.
   The ipc object is *not* locked on exit.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_lock</refname>
 <refpurpose>
     lock an ipc structure without rwsem held
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kern_ipc_perm * <function>ipc_lock </function></funcdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
   <paramdef>int <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     ipc id to look for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Look for an id in the ipc ids idr and lock the associated ipc object.
   </para><para>

   The ipc object is locked on successful exit.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-obtain-object-check">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_obtain_object_check</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_obtain_object_check</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kern_ipc_perm * <function>ipc_obtain_object_check </function></funcdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
   <paramdef>int <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     ipc id to look for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Similar to <function>ipc_obtain_object</function> but also checks
   the ipc object reference counter.
   </para><para>

   Call inside the RCU critical section.
   The ipc object is *not* locked on exit.
</para>
</refsect1>
</refentry>

<refentry id="API-ipcget">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipcget</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipcget</refname>
 <refpurpose>
     Common sys_*<function>get</function> code
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ipcget </function></funcdef>
   <paramdef>struct ipc_namespace * <parameter>ns</parameter></paramdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
   <paramdef>const struct ipc_ops * <parameter>ops</parameter></paramdef>
   <paramdef>struct ipc_params * <parameter>params</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ns</parameter></term>
   <listitem>
    <para>
     namespace
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     ipc identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     operations to be called on ipc object creation, permission checks
     and further checks
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     the parameters needed by the previous operations.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Common routine called by <function>sys_msgget</function>, <function>sys_semget</function> and <function>sys_shmget</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-update-perm">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_update_perm</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_update_perm</refname>
 <refpurpose>
     update the permissions of an ipc object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ipc_update_perm </function></funcdef>
   <paramdef>struct ipc64_perm * <parameter>in</parameter></paramdef>
   <paramdef>struct kern_ipc_perm * <parameter>out</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>in</parameter></term>
   <listitem>
    <para>
     the permission given as input.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>out</parameter></term>
   <listitem>
    <para>
     the permission of the ipc to set.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-ipcctl-pre-down-nolock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipcctl_pre_down_nolock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipcctl_pre_down_nolock</refname>
 <refpurpose>
     retrieve an ipc and check permissions for some IPC_XXX cmd
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kern_ipc_perm * <function>ipcctl_pre_down_nolock </function></funcdef>
   <paramdef>struct ipc_namespace * <parameter>ns</parameter></paramdef>
   <paramdef>struct ipc_ids * <parameter>ids</parameter></paramdef>
   <paramdef>int <parameter>id</parameter></paramdef>
   <paramdef>int <parameter>cmd</parameter></paramdef>
   <paramdef>struct ipc64_perm * <parameter>perm</parameter></paramdef>
   <paramdef>int <parameter>extra_perm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ns</parameter></term>
   <listitem>
    <para>
     ipc namespace
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     the table of ids where to look for the ipc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the id of the ipc to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     the cmd to check
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>perm</parameter></term>
   <listitem>
    <para>
     the permission to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>extra_perm</parameter></term>
   <listitem>
    <para>
     one extra permission parameter used by msq
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function does some common audit and permissions check for some IPC_XXX
   cmd and is called from semctl_down, shmctl_down and msgctl_down.
   It must be called without any lock held and
   - retrieves the ipc with the given id in the given table.
   - performs some audit and permission check, depending on the given cmd
   - returns a pointer to the ipc object or otherwise, the corresponding error.
   </para><para>

   Call holding the both the rwsem and the rcu read lock.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-parse-version">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_parse_version</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_parse_version</refname>
 <refpurpose>
     ipc call version
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ipc_parse_version </function></funcdef>
   <paramdef>int * <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     pointer to command
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return IPC_64 for new style IPC and IPC_OLD for old style IPC.
   The <parameter>cmd</parameter> value is turned from an encoding command and version into
   just the command code.
</para>
</refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="kfifo">
     <title>FIFO Buffer</title>
     <sect1><title>kfifo interface</title>
<!-- include/linux/kfifo.h -->
<refentry id="API-DECLARE-KFIFO-PTR">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>DECLARE_KFIFO_PTR</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>DECLARE_KFIFO_PTR</refname>
 <refpurpose>
  macro to declare a fifo pointer object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>DECLARE_KFIFO_PTR </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     name of the declared fifo
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of the fifo elements
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-DECLARE-KFIFO">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>DECLARE_KFIFO</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>DECLARE_KFIFO</refname>
 <refpurpose>
     macro to declare a fifo object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>DECLARE_KFIFO </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>type</parameter></paramdef>
   <paramdef> <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     name of the declared fifo
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of the fifo elements
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the number of elements in the fifo, this must be a power of 2
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-INIT-KFIFO">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>INIT_KFIFO</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>INIT_KFIFO</refname>
 <refpurpose>
     Initialize a fifo declared by DECLARE_KFIFO
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>INIT_KFIFO </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     name of the declared fifo datatype
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-DEFINE-KFIFO">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>DEFINE_KFIFO</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>DEFINE_KFIFO</refname>
 <refpurpose>
     macro to define and initialize a fifo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>DEFINE_KFIFO </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>type</parameter></paramdef>
   <paramdef> <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     name of the declared fifo datatype
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of the fifo elements
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the number of elements in the fifo, this must be a power of 2
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the macro can be used for global and local fifo data type variables.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-initialized">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_initialized</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_initialized</refname>
 <refpurpose>
     Check if the fifo is initialized
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_initialized </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return <constant>true</constant> if fifo is initialized, otherwise <constant>false</constant>.
   Assumes the fifo was 0 before.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-esize">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_esize</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_esize</refname>
 <refpurpose>
     returns the size of the element managed by the fifo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_esize </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-recsize">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_recsize</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_recsize</refname>
 <refpurpose>
     returns the size of the record length field
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_recsize </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_size</refname>
 <refpurpose>
     returns the size of the fifo in elements
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_size </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_reset</refname>
 <refpurpose>
     removes the entire fifo content
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_reset </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   usage of <function>kfifo_reset</function> is dangerous. It should be only called when the
   fifo is exclusived locked or when it is secured that no other thread is
   accessing the fifo.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-reset-out">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_reset_out</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_reset_out</refname>
 <refpurpose>
     skip fifo content
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_reset_out </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   The usage of <function>kfifo_reset_out</function> is safe until it will be only called
   from the reader thread and there is only one concurrent reader. Otherwise
   it is dangerous and must be handled in the same way as <function>kfifo_reset</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-len">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_len</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_len</refname>
 <refpurpose>
     returns the number of used elements in the fifo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_len </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-is-empty">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_is_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_is_empty</refname>
 <refpurpose>
     returns true if the fifo is empty
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_is_empty </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-is-full">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_is_full</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_is_full</refname>
 <refpurpose>
     returns true if the fifo is full
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_is_full </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-avail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_avail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_avail</refname>
 <refpurpose>
     returns the number of unused elements in the fifo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_avail </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-skip">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_skip</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_skip</refname>
 <refpurpose>
     skip output data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_skip </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-peek-len">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_peek_len</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_peek_len</refname>
 <refpurpose>
     gets the size of the next fifo record
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_peek_len </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function returns the size of the next fifo record in number of bytes.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_alloc</refname>
 <refpurpose>
     dynamically allocates a new fifo buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_alloc </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>size</parameter></paramdef>
   <paramdef> <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     pointer to the fifo
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the number of elements in the fifo, this must be a power of 2
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     get_free_pages mask, passed to <function>kmalloc</function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro dynamically allocates a new fifo buffer.
   </para><para>

   The numer of elements will be rounded-up to a power of 2.
   The fifo will be release with <function>kfifo_free</function>.
   Return 0 if no error, otherwise an error code.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_free</refname>
 <refpurpose>
     frees the fifo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_free </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     the fifo to be freed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_init</refname>
 <refpurpose>
     initialize a fifo using a preallocated buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_init </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>buffer</parameter></paramdef>
   <paramdef> <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     the fifo to assign the buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     the preallocated buffer to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the size of the internal buffer, this have to be a power of 2
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro initialize a fifo using a preallocated buffer.
   </para><para>

   The numer of elements will be rounded-up to a power of 2.
   Return 0 if no error, otherwise an error code.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_put</refname>
 <refpurpose>
     put data into the fifo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_put </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     the data to be added
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro copies the given value into the fifo.
   It returns 0 if the fifo was full. Otherwise it returns the number
   processed elements.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macro.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_get</refname>
 <refpurpose>
     get data from the fifo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_get </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     address where to store the data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro reads the data from the fifo.
   It returns 0 if the fifo was empty. Otherwise it returns the number
   processed elements.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macro.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-peek">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_peek</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_peek</refname>
 <refpurpose>
     get data from the fifo without removing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_peek </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     address where to store the data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This reads the data from the fifo without removing it from the fifo.
   It returns 0 if the fifo was empty. Otherwise it returns the number
   processed elements.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macro.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-in">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_in</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_in</refname>
 <refpurpose>
     put data into the fifo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_in </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>buf</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     the data to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     number of elements to be added
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro copies the given buffer into the fifo and returns the
   number of copied elements.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macro.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-in-spinlocked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_in_spinlocked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_in_spinlocked</refname>
 <refpurpose>
     put data into the fifo using a spinlock for locking
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_in_spinlocked </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>buf</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
   <paramdef> <parameter>lock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     the data to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     number of elements to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     pointer to the spinlock to use for locking
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro copies the given values buffer into the fifo and returns the
   number of copied elements.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-out">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_out</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_out</refname>
 <refpurpose>
     get data from the fifo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_out </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>buf</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     pointer to the storage buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     max. number of elements to get
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro get some data from the fifo and return the numbers of elements
   copied.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macro.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-out-spinlocked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_out_spinlocked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_out_spinlocked</refname>
 <refpurpose>
     get data from the fifo using a spinlock for locking
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_out_spinlocked </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>buf</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
   <paramdef> <parameter>lock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     pointer to the storage buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     max. number of elements to get
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     pointer to the spinlock to use for locking
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro get the data from the fifo and return the numbers of elements
   copied.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-from-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_from_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_from_user</refname>
 <refpurpose>
     puts some data from user space into the fifo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_from_user </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>from</parameter></paramdef>
   <paramdef> <parameter>len</parameter></paramdef>
   <paramdef> <parameter>copied</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     pointer to the data to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     the length of the data to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>copied</parameter></term>
   <listitem>
    <para>
     pointer to output variable to store the number of copied bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro copies at most <parameter>len</parameter> bytes from the <parameter>from</parameter> into the
   fifo, depending of the available space and returns -EFAULT/0.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macro.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-to-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_to_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_to_user</refname>
 <refpurpose>
     copies data from the fifo into user space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_to_user </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>to</parameter></paramdef>
   <paramdef> <parameter>len</parameter></paramdef>
   <paramdef> <parameter>copied</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     where the data must be copied
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     the size of the destination buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>copied</parameter></term>
   <listitem>
    <para>
     pointer to output variable to store the number of copied bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro copies at most <parameter>len</parameter> bytes from the fifo into the
   <parameter>to</parameter> buffer and returns -EFAULT/0.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macro.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-dma-in-prepare">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_dma_in_prepare</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_dma_in_prepare</refname>
 <refpurpose>
     setup a scatterlist for DMA input
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_dma_in_prepare </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>sgl</parameter></paramdef>
   <paramdef> <parameter>nents</parameter></paramdef>
   <paramdef> <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sgl</parameter></term>
   <listitem>
    <para>
     pointer to the scatterlist array
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nents</parameter></term>
   <listitem>
    <para>
     number of entries in the scatterlist array
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of elements to transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro fills a scatterlist for DMA input.
   It returns the number entries in the scatterlist array.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macros.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-dma-in-finish">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_dma_in_finish</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_dma_in_finish</refname>
 <refpurpose>
     finish a DMA IN operation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_dma_in_finish </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes to received
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro finish a DMA IN operation. The in counter will be updated by
   the len parameter. No error checking will be done.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macros.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-dma-out-prepare">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_dma_out_prepare</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_dma_out_prepare</refname>
 <refpurpose>
     setup a scatterlist for DMA output
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_dma_out_prepare </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>sgl</parameter></paramdef>
   <paramdef> <parameter>nents</parameter></paramdef>
   <paramdef> <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sgl</parameter></term>
   <listitem>
    <para>
     pointer to the scatterlist array
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nents</parameter></term>
   <listitem>
    <para>
     number of entries in the scatterlist array
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of elements to transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro fills a scatterlist for DMA output which at most <parameter>len</parameter> bytes
   to transfer.
   It returns the number entries in the scatterlist array.
   A zero means there is no space available and the scatterlist is not filled.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macros.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-dma-out-finish">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_dma_out_finish</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_dma_out_finish</refname>
 <refpurpose>
     finish a DMA OUT operation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_dma_out_finish </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes transferred
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro finish a DMA OUT operation. The out counter will be updated by
   the len parameter. No error checking will be done.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macros.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-out-peek">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_out_peek</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_out_peek</refname>
 <refpurpose>
     gets some data from the fifo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>kfifo_out_peek </function></funcdef>
   <paramdef> <parameter>fifo</parameter></paramdef>
   <paramdef> <parameter>buf</parameter></paramdef>
   <paramdef> <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     address of the fifo to be used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     pointer to the storage buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     max. number of elements to get
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro get the data from the fifo and return the numbers of elements
   copied. The data is not removed from the fifo.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these macro.
</para>
</refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="relayfs">
     <title>relay interface support</title>

     <para>
	Relay interface support
	is designed to provide an efficient mechanism for tools and
	facilities to relay large amounts of data from kernel space to
	user space.
     </para>

     <sect1><title>relay interface</title>
<!-- kernel/relay.c -->
<refentry id="API-relay-buf-full">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_buf_full</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_buf_full</refname>
 <refpurpose>
  boolean, is the channel buffer full?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>relay_buf_full </function></funcdef>
   <paramdef>struct rchan_buf * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     channel buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 1 if the buffer is full, 0 otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_reset</refname>
 <refpurpose>
     reset the channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>relay_reset </function></funcdef>
   <paramdef>struct rchan * <parameter>chan</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>chan</parameter></term>
   <listitem>
    <para>
     the channel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This has the effect of erasing all data from all channel buffers
   and restarting the channel in its initial state.  The buffers
   are not freed, so any mappings are still in effect.
   </para><para>

   NOTE. Care should be taken that the channel isn't actually
   being used by anything when this call is made.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_open</refname>
 <refpurpose>
     create a new relay channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct rchan * <function>relay_open </function></funcdef>
   <paramdef>const char * <parameter>base_filename</parameter></paramdef>
   <paramdef>struct dentry * <parameter>parent</parameter></paramdef>
   <paramdef>size_t <parameter>subbuf_size</parameter></paramdef>
   <paramdef>size_t <parameter>n_subbufs</parameter></paramdef>
   <paramdef>struct rchan_callbacks * <parameter>cb</parameter></paramdef>
   <paramdef>void * <parameter>private_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>base_filename</parameter></term>
   <listitem>
    <para>
     base name of files to create, <constant>NULL</constant> for buffering only
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     dentry of parent directory, <constant>NULL</constant> for root directory or buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>subbuf_size</parameter></term>
   <listitem>
    <para>
     size of sub-buffers
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n_subbufs</parameter></term>
   <listitem>
    <para>
     number of sub-buffers
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cb</parameter></term>
   <listitem>
    <para>
     client callback functions
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>private_data</parameter></term>
   <listitem>
    <para>
     user-defined data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns channel pointer if successful, <constant>NULL</constant> otherwise.
   </para><para>

   Creates a channel buffer for each cpu using the sizes and
   attributes specified.  The created channel buffer files
   will be named base_filename0...base_filenameN-1.  File
   permissions will be <constant>S_IRUSR</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-switch-subbuf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_switch_subbuf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_switch_subbuf</refname>
 <refpurpose>
     switch to a new sub-buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>relay_switch_subbuf </function></funcdef>
   <paramdef>struct rchan_buf * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>length</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     channel buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     size of current event
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns either the length passed in or 0 if full.
   </para><para>

   Performs sub-buffer-switch tasks such as invoking callbacks,
   updating padding counts, waking up readers, etc.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-subbufs-consumed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_subbufs_consumed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_subbufs_consumed</refname>
 <refpurpose>
     update the buffer's sub-buffers-consumed count
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>relay_subbufs_consumed </function></funcdef>
   <paramdef>struct rchan * <parameter>chan</parameter></paramdef>
   <paramdef>unsigned int <parameter>cpu</parameter></paramdef>
   <paramdef>size_t <parameter>subbufs_consumed</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>chan</parameter></term>
   <listitem>
    <para>
     the channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     the cpu associated with the channel buffer to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>subbufs_consumed</parameter></term>
   <listitem>
    <para>
     number of sub-buffers to add to current buf's count
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds to the channel buffer's consumed sub-buffer count.
   subbufs_consumed should be the number of sub-buffers newly consumed,
   not the total consumed.
   </para><para>

   NOTE. Kernel clients don't need to call this function if the channel
   mode is 'overwrite'.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-close">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_close</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_close</refname>
 <refpurpose>
     close the channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>relay_close </function></funcdef>
   <paramdef>struct rchan * <parameter>chan</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>chan</parameter></term>
   <listitem>
    <para>
     the channel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Closes all channel buffers and frees the channel.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_flush</refname>
 <refpurpose>
     close the channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>relay_flush </function></funcdef>
   <paramdef>struct rchan * <parameter>chan</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>chan</parameter></term>
   <listitem>
    <para>
     the channel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Flushes all channel buffers, i.e. forces buffer switch.
</para>
</refsect1>
</refentry>

<!-- kernel/relay.c -->
<refentry id="API-relay-mmap-buf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_mmap_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_mmap_buf</refname>
 <refpurpose>
  mmap channel buffer to process address space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>relay_mmap_buf </function></funcdef>
   <paramdef>struct rchan_buf * <parameter>buf</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     relay channel buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     vm_area_struct describing memory to be mapped
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 if ok, negative on error
   </para><para>

   Caller should already have grabbed mmap_sem.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-alloc-buf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_alloc_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_alloc_buf</refname>
 <refpurpose>
     allocate a channel buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>relay_alloc_buf </function></funcdef>
   <paramdef>struct rchan_buf * <parameter>buf</parameter></paramdef>
   <paramdef>size_t * <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     the buffer struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     total size of the buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a pointer to the resulting buffer, <constant>NULL</constant> if unsuccessful. The
   passed in size will get page aligned, if it isn't already.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-create-buf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_create_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_create_buf</refname>
 <refpurpose>
     allocate and initialize a channel buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct rchan_buf * <function>relay_create_buf </function></funcdef>
   <paramdef>struct rchan * <parameter>chan</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>chan</parameter></term>
   <listitem>
    <para>
     the relay channel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns channel buffer if successful, <constant>NULL</constant> otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-destroy-channel">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_destroy_channel</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_destroy_channel</refname>
 <refpurpose>
     free the channel struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>relay_destroy_channel </function></funcdef>
   <paramdef>struct kref * <parameter>kref</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kref</parameter></term>
   <listitem>
    <para>
     target kernel reference that contains the relay channel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Should only be called from <function>kref_put</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-destroy-buf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_destroy_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_destroy_buf</refname>
 <refpurpose>
     destroy an rchan_buf struct and associated buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>relay_destroy_buf </function></funcdef>
   <paramdef>struct rchan_buf * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     the buffer struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-relay-remove-buf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_remove_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_remove_buf</refname>
 <refpurpose>
     remove a channel buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>relay_remove_buf </function></funcdef>
   <paramdef>struct kref * <parameter>kref</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kref</parameter></term>
   <listitem>
    <para>
     target kernel reference that contains the relay buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes the file from the filesystem, which also frees the
   rchan_buf_struct and the channel buffer.  Should only be called from
   <function>kref_put</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-buf-empty">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_buf_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_buf_empty</refname>
 <refpurpose>
     boolean, is the channel buffer empty?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>relay_buf_empty </function></funcdef>
   <paramdef>struct rchan_buf * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     channel buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 1 if the buffer is empty, 0 otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-wakeup-readers">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wakeup_readers</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>wakeup_readers</refname>
 <refpurpose>
     wake up readers waiting on a channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>wakeup_readers </function></funcdef>
   <paramdef>unsigned long <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     contains the channel buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the timer function used to defer reader waking.
</para>
</refsect1>
</refentry>

<refentry id="API---relay-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__relay_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__relay_reset</refname>
 <refpurpose>
     reset a channel buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__relay_reset </function></funcdef>
   <paramdef>struct rchan_buf * <parameter>buf</parameter></paramdef>
   <paramdef>unsigned int <parameter>init</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     the channel buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>init</parameter></term>
   <listitem>
    <para>
     1 if this is a first-time initialization
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   See <function>relay_reset</function> for description of effect.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-close-buf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_close_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_close_buf</refname>
 <refpurpose>
     close a channel buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>relay_close_buf </function></funcdef>
   <paramdef>struct rchan_buf * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     channel buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Marks the buffer finalized and restores the default callbacks.
   The channel buffer and channel buffer data structure are then freed
   automatically when the last reference is given up.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-hotcpu-callback">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_hotcpu_callback</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_hotcpu_callback</refname>
 <refpurpose>
     CPU hotplug callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>relay_hotcpu_callback </function></funcdef>
   <paramdef>struct notifier_block * <parameter>nb</parameter></paramdef>
   <paramdef>unsigned long <parameter>action</parameter></paramdef>
   <paramdef>void * <parameter>hcpu</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nb</parameter></term>
   <listitem>
    <para>
     notifier block
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>action</parameter></term>
   <listitem>
    <para>
     hotplug action to take
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hcpu</parameter></term>
   <listitem>
    <para>
     CPU number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the success/failure of the operation. (<constant>NOTIFY_OK</constant>, <constant>NOTIFY_BAD</constant>)
</para>
</refsect1>
</refentry>

<refentry id="API-relay-late-setup-files">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_late_setup_files</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_late_setup_files</refname>
 <refpurpose>
     triggers file creation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>relay_late_setup_files </function></funcdef>
   <paramdef>struct rchan * <parameter>chan</parameter></paramdef>
   <paramdef>const char * <parameter>base_filename</parameter></paramdef>
   <paramdef>struct dentry * <parameter>parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>chan</parameter></term>
   <listitem>
    <para>
     channel to operate on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>base_filename</parameter></term>
   <listitem>
    <para>
     base name of files to create
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     dentry of parent directory, <constant>NULL</constant> for root directory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 if successful, non-zero otherwise.
   </para><para>

   Use to setup files for a previously buffer-only channel.
   Useful to do early tracing in kernel, before VFS is up, for example.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-file-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_file_open</refname>
 <refpurpose>
     open file op for relay files
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>relay_file_open </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     the inode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     the file
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Increments the channel buffer refcount.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-file-mmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_mmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_file_mmap</refname>
 <refpurpose>
     mmap file op for relay files
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>relay_file_mmap </function></funcdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     the file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     the vma describing what to map
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls upon <function>relay_mmap_buf</function> to map the file into user space.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-file-poll">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_poll</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_file_poll</refname>
 <refpurpose>
     poll file op for relay files
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>relay_file_poll </function></funcdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>poll_table * <parameter>wait</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     the file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wait</parameter></term>
   <listitem>
    <para>
     poll table
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Poll implemention.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-file-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_file_release</refname>
 <refpurpose>
     release file op for relay files
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>relay_file_release </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     the inode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     the file
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Decrements the channel refcount, as the filesystem is
   no longer using it.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-file-read-subbuf-avail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_read_subbuf_avail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_file_read_subbuf_avail</refname>
 <refpurpose>
     return bytes available in sub-buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>relay_file_read_subbuf_avail </function></funcdef>
   <paramdef>size_t <parameter>read_pos</parameter></paramdef>
   <paramdef>struct rchan_buf * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>read_pos</parameter></term>
   <listitem>
    <para>
     file read position
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     relay channel buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-relay-file-read-start-pos">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_read_start_pos</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_file_read_start_pos</refname>
 <refpurpose>
     find the first available byte to read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>relay_file_read_start_pos </function></funcdef>
   <paramdef>size_t <parameter>read_pos</parameter></paramdef>
   <paramdef>struct rchan_buf * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>read_pos</parameter></term>
   <listitem>
    <para>
     file read position
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     relay channel buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the <parameter>read_pos</parameter> is in the middle of padding, return the
   position of the first actually available byte, otherwise
   return the original value.
</para>
</refsect1>
</refentry>

<refentry id="API-relay-file-read-end-pos">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_read_end_pos</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_file_read_end_pos</refname>
 <refpurpose>
     return the new read position
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>relay_file_read_end_pos </function></funcdef>
   <paramdef>struct rchan_buf * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>read_pos</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     relay channel buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>read_pos</parameter></term>
   <listitem>
    <para>
     file read position
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of bytes to be read
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="modload">
     <title>Module Support</title>
     <sect1><title>Module Loading</title>
<!-- kernel/kmod.c -->
<refentry id="API---request-module">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__request_module</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__request_module</refname>
 <refpurpose>
  try to load a kernel module
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__request_module </function></funcdef>
   <paramdef>bool <parameter>wait</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wait</parameter></term>
   <listitem>
    <para>
     wait (or not) for the operation to complete
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     printf style format string for the name of the module
     @...: arguments as specified in the format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Load a module using the user mode module loader. The function returns
   zero on success or a negative errno code on failure. Note that a
   successful module load does not mean the module did not then unload
   and exit on an error of its own. Callers must check that the service
   they requested is now available not blindly invoke it.
   </para><para>

   If module auto-loading support is disabled then this function
   becomes a no-operation.
</para>
</refsect1>
</refentry>

<refentry id="API-call-usermodehelper-setup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>call_usermodehelper_setup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>call_usermodehelper_setup</refname>
 <refpurpose>
     prepare to call a usermode helper
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct subprocess_info * <function>call_usermodehelper_setup </function></funcdef>
   <paramdef>char * <parameter>path</parameter></paramdef>
   <paramdef>char ** <parameter>argv</parameter></paramdef>
   <paramdef>char ** <parameter>envp</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>int (*<parameter>init</parameter>)
     <funcparams>struct subprocess_info *info, struct cred *new</funcparams></paramdef>
   <paramdef>void (*<parameter>cleanup</parameter>)
     <funcparams>struct subprocess_info *info</funcparams></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>path</parameter></term>
   <listitem>
    <para>
     path to usermode executable
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>argv</parameter></term>
   <listitem>
    <para>
     arg vector for process
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>envp</parameter></term>
   <listitem>
    <para>
     environment for process
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     gfp mask for memory allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>init</parameter></term>
   <listitem>
    <para>
     an init function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cleanup</parameter></term>
   <listitem>
    <para>
     a cleanup function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     arbitrary context sensitive data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns either <constant>NULL</constant> on allocation failure, or a subprocess_info
   structure.  This should be passed to call_usermodehelper_exec to
   exec the process and free the structure.
   </para><para>

   The init function is used to customize the helper process prior to
   exec.  A non-zero return code causes the process to error out, exit,
   and return the failure to the calling process
   </para><para>

   The cleanup function is just before ethe subprocess_info is about to
   be freed.  This can be used for freeing the argv and envp.  The
   Function must be runnable in either a process context or the
   context in which call_usermodehelper_exec is called.
</para>
</refsect1>
</refentry>

<refentry id="API-call-usermodehelper-exec">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>call_usermodehelper_exec</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>call_usermodehelper_exec</refname>
 <refpurpose>
     start a usermode application
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>call_usermodehelper_exec </function></funcdef>
   <paramdef>struct subprocess_info * <parameter>sub_info</parameter></paramdef>
   <paramdef>int <parameter>wait</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sub_info</parameter></term>
   <listitem>
    <para>
     information about the subprocessa
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wait</parameter></term>
   <listitem>
    <para>
     wait for the application to finish and return status.
     when UMH_NO_WAIT don't wait at all, but you get no useful error back
     when the program couldn't be exec'ed. This makes it safe to call
     from interrupt context.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Runs a user-space application.  The application is started
   asynchronously if wait is not set, and runs as a child of keventd.
   (ie. it runs with full root capabilities).
</para>
</refsect1>
</refentry>

<refentry id="API-call-usermodehelper">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>call_usermodehelper</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>call_usermodehelper</refname>
 <refpurpose>
     prepare and start a usermode application
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>call_usermodehelper </function></funcdef>
   <paramdef>char * <parameter>path</parameter></paramdef>
   <paramdef>char ** <parameter>argv</parameter></paramdef>
   <paramdef>char ** <parameter>envp</parameter></paramdef>
   <paramdef>int <parameter>wait</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>path</parameter></term>
   <listitem>
    <para>
     path to usermode executable
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>argv</parameter></term>
   <listitem>
    <para>
     arg vector for process
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>envp</parameter></term>
   <listitem>
    <para>
     environment for process
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wait</parameter></term>
   <listitem>
    <para>
     wait for the application to finish and return status.
     when UMH_NO_WAIT don't wait at all, but you get no useful error back
     when the program couldn't be exec'ed. This makes it safe to call
     from interrupt context.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is the equivalent to use <function>call_usermodehelper_setup</function> and
   <function>call_usermodehelper_exec</function>.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Inter Module support</title>
        <para>
           Refer to the file kernel/module.c for more information.
        </para>
<!-- FIXME: Removed for now since no structured comments in source
X!Ekernel/module.c
-->
     </sect1>
  </chapter>

  <chapter id="hardware">
     <title>Hardware Interfaces</title>
     <sect1><title>Interrupt Handling</title>
<!-- kernel/irq/manage.c -->
<refentry id="API-synchronize-hardirq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>synchronize_hardirq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>synchronize_hardirq</refname>
 <refpurpose>
  wait for pending hard IRQ handlers (on other CPUs)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>synchronize_hardirq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     interrupt number to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function waits for any pending hard IRQ handlers for this
   interrupt to complete before returning. If you use this
   function while holding a resource the IRQ handler may need you
   will deadlock. It does not take associated threaded handlers
   into account.
   </para><para>

   Do not use this for shutdown scenarios where you must be sure
   that all parts (hardirq and threaded handler) have completed.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   false if a threaded handler is active.
   </para><para>

   This function may be called - with care - from IRQ context.
</para>
</refsect1>
</refentry>

<refentry id="API-synchronize-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>synchronize_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>synchronize_irq</refname>
 <refpurpose>
     wait for pending IRQ handlers (on other CPUs)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>synchronize_irq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     interrupt number to wait for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function waits for any pending IRQ handlers for this interrupt
   to complete before returning. If you use this function while
   holding a resource the IRQ handler may need you will deadlock.
   </para><para>

   This function may be called - with care - from IRQ context.
</para>
</refsect1>
</refentry>

<refentry id="API-irq-set-affinity-notifier">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>irq_set_affinity_notifier</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>irq_set_affinity_notifier</refname>
 <refpurpose>
     control notification of IRQ affinity changes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>irq_set_affinity_notifier </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
   <paramdef>struct irq_affinity_notify * <parameter>notify</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     Interrupt for which to enable/disable notification
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>notify</parameter></term>
   <listitem>
    <para>
     Context for notification, or <constant>NULL</constant> to disable
     notification.  Function pointers must be initialised;
     the other fields will be initialised by this function.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Must be called in process context.  Notification may only be enabled
   after the IRQ is allocated and must be disabled before the IRQ is
   freed using <function>free_irq</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-disable-irq-nosync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disable_irq_nosync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disable_irq_nosync</refname>
 <refpurpose>
     disable an irq without waiting
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>disable_irq_nosync </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     Interrupt to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Disable the selected interrupt line.  Disables and Enables are
   nested.
   Unlike <function>disable_irq</function>, this function does not ensure existing
   instances of the IRQ handler have completed before returning.
   </para><para>

   This function may be called from IRQ context.
</para>
</refsect1>
</refentry>

<refentry id="API-disable-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disable_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disable_irq</refname>
 <refpurpose>
     disable an irq and wait for completion
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>disable_irq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     Interrupt to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Disable the selected interrupt line.  Enables and Disables are
   nested.
   This function waits for any pending IRQ handlers for this interrupt
   to complete before returning. If you use this function while
   holding a resource the IRQ handler may need you will deadlock.
   </para><para>

   This function may be called - with care - from IRQ context.
</para>
</refsect1>
</refentry>

<refentry id="API-disable-hardirq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disable_hardirq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disable_hardirq</refname>
 <refpurpose>
     disables an irq and waits for hardirq completion
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>disable_hardirq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     Interrupt to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Disable the selected interrupt line.  Enables and Disables are
   nested.
   This function waits for any pending hard IRQ handlers for this
   interrupt to complete before returning. If you use this function while
   holding a resource the hard IRQ handler may need you will deadlock.
   </para><para>

   When used to optimistically disable an interrupt from atomic context
   the return value must be checked.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   false if a threaded handler is active.
   </para><para>

   This function may be called - with care - from IRQ context.
</para>
</refsect1>
</refentry>

<refentry id="API-enable-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enable_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enable_irq</refname>
 <refpurpose>
     enable handling of an irq
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>enable_irq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     Interrupt to enable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Undoes the effect of one call to <function>disable_irq</function>.  If this
   matches the last disable, processing of interrupts on this
   IRQ line is re-enabled.
   </para><para>

   This function may be called from IRQ context only when
   desc-&gt;irq_data.chip-&gt;bus_lock and desc-&gt;chip-&gt;bus_sync_unlock are NULL !
</para>
</refsect1>
</refentry>

<refentry id="API-irq-set-irq-wake">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>irq_set_irq_wake</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>irq_set_irq_wake</refname>
 <refpurpose>
     control irq power management wakeup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>irq_set_irq_wake </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
   <paramdef>unsigned int <parameter>on</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     interrupt to control
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>on</parameter></term>
   <listitem>
    <para>
     enable/disable power management wakeup
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enable/disable power management wakeup mode, which is
   disabled by default.  Enables and disables must match,
   just as they match for non-wakeup mode support.
   </para><para>

   Wakeup mode lets this IRQ wake the system from sleep
   states like <quote>suspend to RAM</quote>.
</para>
</refsect1>
</refentry>

<refentry id="API-irq-wake-thread">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>irq_wake_thread</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>irq_wake_thread</refname>
 <refpurpose>
     wake the irq thread for the action identified by dev_id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>irq_wake_thread </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
   <paramdef>void * <parameter>dev_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     Interrupt line
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev_id</parameter></term>
   <listitem>
    <para>
     Device identity for which the thread should be woken
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-setup-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>setup_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>setup_irq</refname>
 <refpurpose>
     setup an interrupt
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>setup_irq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
   <paramdef>struct irqaction * <parameter>act</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     Interrupt line to setup
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>act</parameter></term>
   <listitem>
    <para>
     irqaction for the interrupt
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Used to statically setup interrupts in the early boot process.
</para>
</refsect1>
</refentry>

<refentry id="API-remove-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>remove_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>remove_irq</refname>
 <refpurpose>
     free an interrupt
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>remove_irq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
   <paramdef>struct irqaction * <parameter>act</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     Interrupt line to free
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>act</parameter></term>
   <listitem>
    <para>
     irqaction for the interrupt
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Used to remove interrupts statically setup by the early boot process.
</para>
</refsect1>
</refentry>

<refentry id="API-free-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>free_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>free_irq</refname>
 <refpurpose>
     free an interrupt allocated with request_irq
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>free_irq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
   <paramdef>void * <parameter>dev_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     Interrupt line to free
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev_id</parameter></term>
   <listitem>
    <para>
     Device identity to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove an interrupt handler. The handler is removed and if the
   interrupt line is no longer in use by any driver it is disabled.
   On a shared IRQ the caller must ensure the interrupt is disabled
   on the card it drives before calling this function. The function
   does not return until any executing interrupts for this IRQ
   have completed.
   </para><para>

   This function must not be called from interrupt context.
</para>
</refsect1>
</refentry>

<refentry id="API-request-threaded-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_threaded_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>request_threaded_irq</refname>
 <refpurpose>
     allocate an interrupt line
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>request_threaded_irq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
   <paramdef>irq_handler_t <parameter>handler</parameter></paramdef>
   <paramdef>irq_handler_t <parameter>thread_fn</parameter></paramdef>
   <paramdef>unsigned long <parameter>irqflags</parameter></paramdef>
   <paramdef>const char * <parameter>devname</parameter></paramdef>
   <paramdef>void * <parameter>dev_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     Interrupt line to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
     Function to be called when the IRQ occurs.
     Primary handler for threaded interrupts
     If NULL and thread_fn != NULL the default
     primary handler is installed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>thread_fn</parameter></term>
   <listitem>
    <para>
     Function called from the irq handler thread
     If NULL, no irq thread is created
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>irqflags</parameter></term>
   <listitem>
    <para>
     Interrupt type flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devname</parameter></term>
   <listitem>
    <para>
     An ascii name for the claiming device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev_id</parameter></term>
   <listitem>
    <para>
     A cookie passed back to the handler function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call allocates interrupt resources and enables the
   interrupt line and IRQ handling. From the point this
   call is made your handler function may be invoked. Since
   your handler function must clear any interrupt the board
   raises, you must take care both to initialise your hardware
   and to set up the interrupt handler in the right order.
   </para><para>

   If you want to set up a threaded irq handler for your device
   then you need to supply <parameter>handler</parameter> and <parameter>thread_fn</parameter>. <parameter>handler</parameter> is
   still called in hard interrupt context and has to check
   whether the interrupt originates from the device. If yes it
   needs to disable the interrupt on the device and return
   IRQ_WAKE_THREAD which will wake up the handler thread and run
   <parameter>thread_fn</parameter>. This split handler design is necessary to support
   shared interrupts.
   </para><para>

   Dev_id must be globally unique. Normally the address of the
   device data structure is used as the cookie. Since the handler
   receives this value it makes sense to use it.
   </para><para>

   If your interrupt is shared you must pass a non NULL dev_id
   as this is required when freeing the interrupt.
</para>
</refsect1>
<refsect1>
<title>Flags</title>
<para>
   </para><para>

   IRQF_SHARED		Interrupt is shared
   IRQF_TRIGGER_*		Specify active edge(s) or level
</para>
</refsect1>
</refentry>

<refentry id="API-request-any-context-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_any_context_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>request_any_context_irq</refname>
 <refpurpose>
     allocate an interrupt line
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>request_any_context_irq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
   <paramdef>irq_handler_t <parameter>handler</parameter></paramdef>
   <paramdef>unsigned long <parameter>flags</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>void * <parameter>dev_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     Interrupt line to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
     Function to be called when the IRQ occurs.
     Threaded handler for threaded interrupts.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     Interrupt type flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     An ascii name for the claiming device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev_id</parameter></term>
   <listitem>
    <para>
     A cookie passed back to the handler function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call allocates interrupt resources and enables the
   interrupt line and IRQ handling. It selects either a
   hardirq or threaded handling method depending on the
   context.
   </para><para>

   On failure, it returns a negative value. On success,
   it returns either IRQC_IS_HARDIRQ or IRQC_IS_NESTED.
</para>
</refsect1>
</refentry>

     </sect1>

     <sect1><title>DMA Channels</title>
<!-- kernel/dma.c -->
<refentry id="API-request-dma">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_dma</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>request_dma</refname>
 <refpurpose>
  request and reserve a system DMA channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>request_dma </function></funcdef>
   <paramdef>unsigned int <parameter>dmanr</parameter></paramdef>
   <paramdef>const char * <parameter>device_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmanr</parameter></term>
   <listitem>
    <para>
     DMA channel number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device_id</parameter></term>
   <listitem>
    <para>
     reserving device ID string, used in /proc/dma
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-free-dma">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>free_dma</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>free_dma</refname>
 <refpurpose>
     free a reserved system DMA channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>free_dma </function></funcdef>
   <paramdef>unsigned int <parameter>dmanr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmanr</parameter></term>
   <listitem>
    <para>
     DMA channel number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>

     <sect1><title>Resources Management</title>
<!-- kernel/resource.c -->
<refentry id="API-request-resource-conflict">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_resource_conflict</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>request_resource_conflict</refname>
 <refpurpose>
  request and reserve an I/O or memory resource
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct resource * <function>request_resource_conflict </function></funcdef>
   <paramdef>struct resource * <parameter>root</parameter></paramdef>
   <paramdef>struct resource * <parameter>new</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>root</parameter></term>
   <listitem>
    <para>
     root resource descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     resource descriptor desired by caller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success, conflict resource on error.
</para>
</refsect1>
</refentry>

<refentry id="API-reallocate-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>reallocate_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>reallocate_resource</refname>
 <refpurpose>
     allocate a slot in the resource tree given range &amp; alignment. The resource will be relocated if the new size cannot be reallocated in the current location.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>reallocate_resource </function></funcdef>
   <paramdef>struct resource * <parameter>root</parameter></paramdef>
   <paramdef>struct resource * <parameter>old</parameter></paramdef>
   <paramdef>resource_size_t <parameter>newsize</parameter></paramdef>
   <paramdef>struct resource_constraint * <parameter>constraint</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>root</parameter></term>
   <listitem>
    <para>
     root resource descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     resource descriptor desired by caller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>newsize</parameter></term>
   <listitem>
    <para>
     new size of the resource descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>constraint</parameter></term>
   <listitem>
    <para>
     the size and alignment constraints to be met.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-lookup-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>lookup_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>lookup_resource</refname>
 <refpurpose>
     find an existing resource by a resource start address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct resource * <function>lookup_resource </function></funcdef>
   <paramdef>struct resource * <parameter>root</parameter></paramdef>
   <paramdef>resource_size_t <parameter>start</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>root</parameter></term>
   <listitem>
    <para>
     root resource descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     resource start address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a pointer to the resource if found, NULL otherwise
</para>
</refsect1>
</refentry>

<refentry id="API-insert-resource-conflict">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>insert_resource_conflict</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>insert_resource_conflict</refname>
 <refpurpose>
     Inserts resource in the resource tree
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct resource * <function>insert_resource_conflict </function></funcdef>
   <paramdef>struct resource * <parameter>parent</parameter></paramdef>
   <paramdef>struct resource * <parameter>new</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent of the new resource
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     new resource to insert
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success, conflict resource if the resource can't be inserted.
   </para><para>

   This function is equivalent to request_resource_conflict when no conflict
   happens. If a conflict happens, and the conflicting resources
   entirely fit within the range of the new resource, then the new
   resource is inserted and the conflicting resources become children of
   the new resource.
</para>
</refsect1>
</refentry>

<refentry id="API-insert-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>insert_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>insert_resource</refname>
 <refpurpose>
     Inserts a resource in the resource tree
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>insert_resource </function></funcdef>
   <paramdef>struct resource * <parameter>parent</parameter></paramdef>
   <paramdef>struct resource * <parameter>new</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent of the new resource
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     new resource to insert
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success, -EBUSY if the resource can't be inserted.
</para>
</refsect1>
</refentry>

<refentry id="API-insert-resource-expand-to-fit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>insert_resource_expand_to_fit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>insert_resource_expand_to_fit</refname>
 <refpurpose>
     Insert a resource into the resource tree
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>insert_resource_expand_to_fit </function></funcdef>
   <paramdef>struct resource * <parameter>root</parameter></paramdef>
   <paramdef>struct resource * <parameter>new</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>root</parameter></term>
   <listitem>
    <para>
     root resource descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     new resource to insert
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Insert a resource into the resource tree, possibly expanding it in order
   to make it encompass any conflicting resources.
</para>
</refsect1>
</refentry>

<refentry id="API-resource-alignment">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>resource_alignment</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>resource_alignment</refname>
 <refpurpose>
     calculate resource's alignment
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>resource_size_t <function>resource_alignment </function></funcdef>
   <paramdef>struct resource * <parameter>res</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     resource pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns alignment on success, 0 (invalid alignment) on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-release-mem-region-adjustable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>release_mem_region_adjustable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>release_mem_region_adjustable</refname>
 <refpurpose>
     release a previously reserved memory region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>release_mem_region_adjustable </function></funcdef>
   <paramdef>struct resource * <parameter>parent</parameter></paramdef>
   <paramdef>resource_size_t <parameter>start</parameter></paramdef>
   <paramdef>resource_size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent resource descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     resource start address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     resource region size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This interface is intended for memory hot-delete.  The requested region
   is released from a currently busy memory resource.  The requested region
   must either match exactly or fit into a single busy resource entry.  In
   the latter case, the remaining resource is adjusted accordingly.
   Existing children of the busy memory resource must be immutable in the
   request.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   - Additional release conditions, such as overlapping region, can be
   supported after they are confirmed as valid cases.
   - When a busy memory resource gets split into two entries, the code
   assumes that all children remain in the lower address entry for
   simplicity.  Enhance this logic when necessary.
</para>
</refsect1>
</refentry>

<!-- kernel/resource.c -->
<refentry id="API-request-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>request_resource</refname>
 <refpurpose>
  request and reserve an I/O or memory resource
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>request_resource </function></funcdef>
   <paramdef>struct resource * <parameter>root</parameter></paramdef>
   <paramdef>struct resource * <parameter>new</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>root</parameter></term>
   <listitem>
    <para>
     root resource descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     resource descriptor desired by caller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success, negative error code on error.
</para>
</refsect1>
</refentry>

<refentry id="API-release-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>release_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>release_resource</refname>
 <refpurpose>
     release a previously reserved resource
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>release_resource </function></funcdef>
   <paramdef>struct resource * <parameter>old</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     resource pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-allocate-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>allocate_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>allocate_resource</refname>
 <refpurpose>
     allocate empty slot in the resource tree given range &amp; alignment. The resource will be reallocated with a new size if it was already allocated
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>allocate_resource </function></funcdef>
   <paramdef>struct resource * <parameter>root</parameter></paramdef>
   <paramdef>struct resource * <parameter>new</parameter></paramdef>
   <paramdef>resource_size_t <parameter>size</parameter></paramdef>
   <paramdef>resource_size_t <parameter>min</parameter></paramdef>
   <paramdef>resource_size_t <parameter>max</parameter></paramdef>
   <paramdef>resource_size_t <parameter>align</parameter></paramdef>
   <paramdef>resource_size_t (*<parameter>alignf</parameter>)
     <funcparams>void *, 						const struct resource *, 						resource_size_t, 						resource_size_t</funcparams></paramdef>
   <paramdef>void * <parameter>alignf_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>root</parameter></term>
   <listitem>
    <para>
     root resource descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     resource descriptor desired by caller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     requested resource region size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     minimum boundary to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     maximum boundary to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>align</parameter></term>
   <listitem>
    <para>
     alignment requested, in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alignf</parameter></term>
   <listitem>
    <para>
     alignment function, optional, called if not NULL
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alignf_data</parameter></term>
   <listitem>
    <para>
     arbitrary data to pass to the <parameter>alignf</parameter> function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-adjust-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>adjust_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>adjust_resource</refname>
 <refpurpose>
     modify a resource's start and size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>adjust_resource </function></funcdef>
   <paramdef>struct resource * <parameter>res</parameter></paramdef>
   <paramdef>resource_size_t <parameter>start</parameter></paramdef>
   <paramdef>resource_size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     resource to modify
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     new start value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     new size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given an existing resource, change its start and size to match the
   arguments.  Returns 0 on success, -EBUSY if it can't fit.
   Existing children of the resource are assumed to be immutable.
</para>
</refsect1>
</refentry>

<refentry id="API---request-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__request_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__request_region</refname>
 <refpurpose>
     create a new busy resource region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct resource * <function>__request_region </function></funcdef>
   <paramdef>struct resource * <parameter>parent</parameter></paramdef>
   <paramdef>resource_size_t <parameter>start</parameter></paramdef>
   <paramdef>resource_size_t <parameter>n</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent resource descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     resource start address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     resource region size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     reserving caller's ID string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     IO resource flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---release-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__release_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__release_region</refname>
 <refpurpose>
     release a previously reserved resource region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__release_region </function></funcdef>
   <paramdef>struct resource * <parameter>parent</parameter></paramdef>
   <paramdef>resource_size_t <parameter>start</parameter></paramdef>
   <paramdef>resource_size_t <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent resource descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     resource start address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     resource region size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The described resource region must match a currently busy region.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-request-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_request_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_request_resource</refname>
 <refpurpose>
     request and reserve an I/O or memory resource
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>devm_request_resource </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct resource * <parameter>root</parameter></paramdef>
   <paramdef>struct resource * <parameter>new</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device for which to request the resource
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>root</parameter></term>
   <listitem>
    <para>
     root of the resource tree from which to request the resource
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     descriptor of the resource to request
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a device-managed version of <function>request_resource</function>. There is usually
   no need to release resources requested by this function explicitly since
   that will be taken care of when the device is unbound from its driver.
   If for some reason the resource needs to be released explicitly, because
   of ordering issues for example, drivers must call <function>devm_release_resource</function>
   rather than the regular <function>release_resource</function>.
   </para><para>

   When a conflict is detected between any existing resources and the newly
   requested resource, an error message will be printed.
   </para><para>

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

<refentry id="API-devm-release-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_release_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_release_resource</refname>
 <refpurpose>
     release a previously requested resource
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>devm_release_resource </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct resource * <parameter>new</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device for which to release the resource
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     descriptor of the resource to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases a resource previously requested using <function>devm_request_resource</function>.
</para>
</refsect1>
</refentry>

     </sect1>

     <sect1><title>MTRR Handling</title>
<!-- arch/x86/kernel/cpu/mtrr/main.c -->
<refentry id="API-mtrr-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mtrr_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mtrr_add</refname>
 <refpurpose>
  Add a memory type region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mtrr_add </function></funcdef>
   <paramdef>unsigned long <parameter>base</parameter></paramdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
   <paramdef>unsigned int <parameter>type</parameter></paramdef>
   <paramdef>bool <parameter>increment</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     Physical base address of region
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Physical size of region
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     Type of MTRR desired
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>increment</parameter></term>
   <listitem>
    <para>
     If this is true do usage counting on the region
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Memory type region registers control the caching on newer Intel and
   non Intel processors. This function allows drivers to request an
   MTRR is added. The details and hardware specifics of each processor's
   implementation are hidden from the caller, but nevertheless the
   caller should expect to need to provide a power of two size on an
   equivalent power of two boundary.
   </para><para>

   If the region cannot be added either because all regions are in use
   or the CPU cannot support it a negative value is returned. On success
   the register number for this entry is returned, but should be treated
   as a cookie only.
   </para><para>

   On a multiprocessor machine the changes are made to all processors.
   This is required on x86 by the Intel processors.
   </para><para>

   The available types are
   </para><para>

   <constant>MTRR_TYPE_UNCACHABLE</constant> - No caching
   </para><para>

   <constant>MTRR_TYPE_WRBACK</constant> - Write data back in bursts whenever
   </para><para>

   <constant>MTRR_TYPE_WRCOMB</constant> - Write data back soon but allow bursts
   </para><para>

   <constant>MTRR_TYPE_WRTHROUGH</constant> - Cache reads but not writes
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
   Needs a quiet flag for the cases where drivers do not mind
   failures and do not wish system log messages to be sent.
</para>
</refsect1>
</refentry>

<refentry id="API-mtrr-del">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mtrr_del</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mtrr_del</refname>
 <refpurpose>
     delete a memory type region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mtrr_del </function></funcdef>
   <paramdef>int <parameter>reg</parameter></paramdef>
   <paramdef>unsigned long <parameter>base</parameter></paramdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>reg</parameter></term>
   <listitem>
    <para>
     Register returned by mtrr_add
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     Physical base address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Size of region
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If register is supplied then base and size are ignored. This is
   how drivers should call it.
   </para><para>

   Releases an MTRR region. If the usage count drops to zero the
   register is freed and the region returns to default state.
   On success the register is returned, on failure a negative error
   code.
</para>
</refsect1>
</refentry>

<refentry id="API-arch-phys-wc-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>arch_phys_wc_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>arch_phys_wc_add</refname>
 <refpurpose>
     add a WC MTRR and handle errors if PAT is unavailable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>arch_phys_wc_add </function></funcdef>
   <paramdef>unsigned long <parameter>base</parameter></paramdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     Physical base address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Size of region
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If PAT is available, this does nothing.  If PAT is unavailable, it
   attempts to add a WC MTRR covering size bytes starting at base and
   logs an error if this fails.
   </para><para>

   Drivers must store the return value to pass to mtrr_del_wc_if_needed,
   but drivers should not try to interpret that return value.
</para>
</refsect1>
</refentry>

     </sect1>

     <sect1><title>PCI Support Library</title>
<!-- drivers/pci/pci.c -->
<refentry id="API-pci-bus-max-busnr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_bus_max_busnr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_bus_max_busnr</refname>
 <refpurpose>
  returns maximum PCI bus number of given bus' children
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned char <function>pci_bus_max_busnr </function></funcdef>
   <paramdef>struct pci_bus * <parameter>bus</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     pointer to PCI bus structure to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a PCI bus, returns the highest PCI bus number present in the set
   including the given PCI bus and its list of child PCI buses.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-find-capability">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_find_capability</refname>
 <refpurpose>
     query for devices' capabilities
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_find_capability </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>cap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cap</parameter></term>
   <listitem>
    <para>
     capability code
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Tell if a device supports a given PCI capability.
   Returns the address of the requested capability structure within the
   device's PCI configuration space or 0 in case the device does not
   support it.  Possible values for <parameter>cap</parameter>:
   </para><para>

   <constant>PCI_CAP_ID_PM</constant>           Power Management
   <constant>PCI_CAP_ID_AGP</constant>          Accelerated Graphics Port
   <constant>PCI_CAP_ID_VPD</constant>          Vital Product Data
   <constant>PCI_CAP_ID_SLOTID</constant>       Slot Identification
   <constant>PCI_CAP_ID_MSI</constant>          Message Signalled Interrupts
   <constant>PCI_CAP_ID_CHSWP</constant>        CompactPCI HotSwap
   <constant>PCI_CAP_ID_PCIX</constant>         PCI-X
   <constant>PCI_CAP_ID_EXP</constant>          PCI Express
</para>
</refsect1>
</refentry>

<refentry id="API-pci-bus-find-capability">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_bus_find_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_bus_find_capability</refname>
 <refpurpose>
     query for devices' capabilities
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_bus_find_capability </function></funcdef>
   <paramdef>struct pci_bus * <parameter>bus</parameter></paramdef>
   <paramdef>unsigned int <parameter>devfn</parameter></paramdef>
   <paramdef>int <parameter>cap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     the PCI bus to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devfn</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cap</parameter></term>
   <listitem>
    <para>
     capability code
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Like <function>pci_find_capability</function> but works for pci devices that do not have a
   pci_dev structure set up yet.
   </para><para>

   Returns the address of the requested capability structure within the
   device's PCI configuration space or 0 in case the device does not
   support it.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-find-next-ext-capability">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_next_ext_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_find_next_ext_capability</refname>
 <refpurpose>
     Find an extended capability
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_find_next_ext_capability </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>start</parameter></paramdef>
   <paramdef>int <parameter>cap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     address at which to start looking (0 to start at beginning of list)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cap</parameter></term>
   <listitem>
    <para>
     capability code
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the address of the next matching extended capability structure
   within the device's PCI configuration space or 0 if the device does
   not support it.  Some capabilities can occur several times, e.g., the
   vendor-specific capability, and this provides a way to find them all.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-find-ext-capability">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_ext_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_find_ext_capability</refname>
 <refpurpose>
     Find an extended capability
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_find_ext_capability </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>cap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cap</parameter></term>
   <listitem>
    <para>
     capability code
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the address of the requested extended capability structure
   within the device's PCI configuration space or 0 if the device does
   not support it.  Possible values for <parameter>cap</parameter>:
   </para><para>

   <constant>PCI_EXT_CAP_ID_ERR</constant>		Advanced Error Reporting
   <constant>PCI_EXT_CAP_ID_VC</constant>		Virtual Channel
   <constant>PCI_EXT_CAP_ID_DSN</constant>		Device Serial Number
   <constant>PCI_EXT_CAP_ID_PWR</constant>		Power Budgeting
</para>
</refsect1>
</refentry>

<refentry id="API-pci-find-next-ht-capability">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_next_ht_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_find_next_ht_capability</refname>
 <refpurpose>
     query a device's Hypertransport capabilities
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_find_next_ht_capability </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>pos</parameter></paramdef>
   <paramdef>int <parameter>ht_cap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     Position from which to continue searching
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ht_cap</parameter></term>
   <listitem>
    <para>
     Hypertransport capability code
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   To be used in conjunction with <function>pci_find_ht_capability</function> to search for
   all capabilities matching <parameter>ht_cap</parameter>. <parameter>pos</parameter> should always be a value returned
   from <function>pci_find_ht_capability</function>.
   </para><para>

   NB. To be 100% safe against broken PCI devices, the caller should take
   steps to avoid an infinite loop.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-find-ht-capability">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_ht_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_find_ht_capability</refname>
 <refpurpose>
     query a device's Hypertransport capabilities
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_find_ht_capability </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>ht_cap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ht_cap</parameter></term>
   <listitem>
    <para>
     Hypertransport capability code
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Tell if a device supports a given Hypertransport capability.
   Returns an address within the device's PCI configuration space
   or 0 in case the device does not support the request capability.
   The address points to the PCI capability, of type PCI_CAP_ID_HT,
   which has a Hypertransport capability matching <parameter>ht_cap</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-find-parent-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_parent_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_find_parent_resource</refname>
 <refpurpose>
     return resource region of parent bus of given region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct resource * <function>pci_find_parent_resource </function></funcdef>
   <paramdef>const struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>struct resource * <parameter>res</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device structure contains resources to be searched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     child resource record for which parent is sought
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   For given resource region of given device, return the resource
   region of parent bus the given region is contained in.
</para>
</refsect1>
</refentry>

<refentry id="API---pci-complete-power-transition">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__pci_complete_power_transition</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__pci_complete_power_transition</refname>
 <refpurpose>
     Complete power transition of a PCI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__pci_complete_power_transition </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>pci_power_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to handle.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     State to put the device into.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should not be called directly by device drivers.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-set-power-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_set_power_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_set_power_state</refname>
 <refpurpose>
     Set the power state of a PCI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_set_power_state </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>pci_power_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to handle.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     PCI power state (D0, D1, D2, D3hot) to put the device into.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Transition a device to a new power state, using the platform firmware and/or
   the device's PCI PM registers.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUE</title>
<para>
   -EINVAL if the requested state is invalid.
   -EIO if device does not support PCI PM or its PM capabilities register has a
   wrong version, or device doesn't support the requested state.
   0 if device already is in the requested state.
   0 if device's power state has been successfully changed.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-choose-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_choose_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_choose_state</refname>
 <refpurpose>
     Choose the power state of a PCI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>pci_power_t <function>pci_choose_state </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>pm_message_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to be suspended
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     target sleep state for the whole system. This is the value
     that is passed to <function>suspend</function> function.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns PCI power state suitable for given device and given system
   message.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-save-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_save_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_save_state</refname>
 <refpurpose>
     save the PCI configuration space of a device before suspending
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_save_state </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     - PCI device that we're dealing with
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pci-restore-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_restore_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_restore_state</refname>
 <refpurpose>
     Restore the saved state of a PCI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_restore_state </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     - PCI device that we're dealing with
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pci-store-saved-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_store_saved_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_store_saved_state</refname>
 <refpurpose>
     Allocate and return an opaque struct containing the device saved state.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_saved_state * <function>pci_store_saved_state </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device that we're dealing with
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return NULL if no state or error.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-load-saved-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_load_saved_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_load_saved_state</refname>
 <refpurpose>
     Reload the provided save state into struct pci_dev.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_load_saved_state </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>struct pci_saved_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device that we're dealing with
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     Saved state returned from <function>pci_store_saved_state</function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pci-load-and-free-saved-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_load_and_free_saved_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_load_and_free_saved_state</refname>
 <refpurpose>
     Reload the save state pointed to by state, and free the memory allocated for it.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_load_and_free_saved_state </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>struct pci_saved_state ** <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device that we're dealing with
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     Pointer to saved state returned from <function>pci_store_saved_state</function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pci-reenable-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_reenable_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_reenable_device</refname>
 <refpurpose>
     Resume abandoned device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_reenable_device </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to be resumed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note this function is a backend of pci_default_resume and is not supposed
   to be called by normal code, write proper resume handler and use it instead.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-enable-device-io">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_device_io</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_enable_device_io</refname>
 <refpurpose>
     Initialize a device for use with IO space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_enable_device_io </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to be initialized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize device before it's used by a driver. Ask low-level code
   to enable I/O resources. Wake up the device if it was suspended.
   Beware, this function can fail.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-enable-device-mem">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_device_mem</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_enable_device_mem</refname>
 <refpurpose>
     Initialize a device for use with Memory space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_enable_device_mem </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to be initialized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize device before it's used by a driver. Ask low-level code
   to enable Memory resources. Wake up the device if it was suspended.
   Beware, this function can fail.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-enable-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_enable_device</refname>
 <refpurpose>
     Initialize device before it's used by a driver.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_enable_device </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to be initialized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize device before it's used by a driver. Ask low-level code
   to enable I/O and memory. Wake up the device if it was suspended.
   Beware, this function can fail.
   </para><para>

   Note we don't actually enable the device many times if we call
   this function repeatedly (we just increment the count).
</para>
</refsect1>
</refentry>

<refentry id="API-pcim-enable-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcim_enable_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pcim_enable_device</refname>
 <refpurpose>
     Managed <function>pci_enable_device</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pcim_enable_device </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>
     PCI device to be initialized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Managed <function>pci_enable_device</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-pcim-pin-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcim_pin_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pcim_pin_device</refname>
 <refpurpose>
     Pin managed PCI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pcim_pin_device </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>
     PCI device to pin
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Pin managed PCI device <parameter>pdev</parameter>.  Pinned device won't be disabled on
   driver detach.  <parameter>pdev</parameter> must have been enabled with
   <function>pcim_enable_device</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-disable-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_disable_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_disable_device</refname>
 <refpurpose>
     Disable PCI device after use
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_disable_device </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to be disabled
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Signal to the system that the PCI device is not in use by the system
   anymore.  This only involves disabling PCI bus-mastering, if active.
   </para><para>

   Note we don't actually disable the device until all callers of
   <function>pci_enable_device</function> have called <function>pci_disable_device</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-set-pcie-reset-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_set_pcie_reset_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_set_pcie_reset_state</refname>
 <refpurpose>
     set reset state for device dev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_set_pcie_reset_state </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>enum pcie_reset_state <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCIe device reset
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     Reset state to enter into
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Sets the PCI reset state for the device.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-pme-capable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_pme_capable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_pme_capable</refname>
 <refpurpose>
     check the capability of PCI device to generate PME#
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>pci_pme_capable </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>pci_power_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to handle.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     PCI state from which device will issue PME#.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pci-pme-active">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_pme_active</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_pme_active</refname>
 <refpurpose>
     enable or disable PCI device's PME# function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_pme_active </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>bool <parameter>enable</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to handle.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>enable</parameter></term>
   <listitem>
    <para>
     'true' to enable PME# generation; 'false' to disable it.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The caller must verify that the device is capable of generating PME# before
   calling this function with <parameter>enable</parameter> equal to 'true'.
</para>
</refsect1>
</refentry>

<refentry id="API---pci-enable-wake">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__pci_enable_wake</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__pci_enable_wake</refname>
 <refpurpose>
     enable PCI device as wakeup event source
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__pci_enable_wake </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>pci_power_t <parameter>state</parameter></paramdef>
   <paramdef>bool <parameter>runtime</parameter></paramdef>
   <paramdef>bool <parameter>enable</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device affected
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     PCI state from which device will issue wakeup events
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     True if the events are to be generated at run time
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>enable</parameter></term>
   <listitem>
    <para>
     True to enable event generation; false to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This enables the device as a wakeup event source, or disables it.
   When such events involves platform-specific hooks, those hooks are
   called automatically by this routine.
   </para><para>

   Devices with legacy power management (no standard PCI PM capabilities)
   always require such platform hooks.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUE</title>
<para>
   0 is returned on success
   -EINVAL is returned if device is not supposed to wake up the system
   Error code depending on the platform is returned if both the platform and
   the native mechanism fail to enable the generation of wake-up events
</para>
</refsect1>
</refentry>

<refentry id="API-pci-wake-from-d3">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_wake_from_d3</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_wake_from_d3</refname>
 <refpurpose>
     enable/disable device to wake up from D3_hot or D3_cold
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_wake_from_d3 </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>bool <parameter>enable</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to prepare
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>enable</parameter></term>
   <listitem>
    <para>
     True to enable wake-up event generation; false to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Many drivers want the device to wake up the system from D3_hot or D3_cold
   and this function allows them to set that up cleanly - <function>pci_enable_wake</function>
   should not be called twice in a row to enable wake-up due to PCI PM vs ACPI
   ordering constraints.
   </para><para>

   This function only returns error code if the device is not capable of
   generating PME# from both D3_hot and D3_cold, and the platform is unable to
   enable wake-up power for it.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-prepare-to-sleep">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_prepare_to_sleep</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_prepare_to_sleep</refname>
 <refpurpose>
     prepare PCI device for system-wide transition into a sleep state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_prepare_to_sleep </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to handle.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Choose the power state appropriate for the device depending on whether
   it can wake up the system and/or is power manageable by the platform
   (PCI_D3hot is the default) and put the device into that state.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-back-from-sleep">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_back_from_sleep</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_back_from_sleep</refname>
 <refpurpose>
     turn PCI device on during system-wide transition into working state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_back_from_sleep </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to handle.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Disable device's system wake-up capability and put it into D0.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-dev-run-wake">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_dev_run_wake</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_dev_run_wake</refname>
 <refpurpose>
     Check if device can generate run-time wake-up events.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>pci_dev_run_wake </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to check.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return true if the device itself is capable of generating wake-up events
   (through the platform or using the native PCIe PME) or if the device supports
   PME and one of its upstream bridges can generate wake-up events.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-common-swizzle">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_common_swizzle</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_common_swizzle</refname>
 <refpurpose>
     swizzle INTx all the way to root bridge
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u8 <function>pci_common_swizzle </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>u8 * <parameter>pinp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pinp</parameter></term>
   <listitem>
    <para>
     pointer to the INTx pin value (1=INTA, 2=INTB, 3=INTD, 4=INTD)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Perform INTx swizzling for a device.  This traverses through all PCI-to-PCI
   bridges all the way up to a PCI root bus.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-release-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_release_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_release_region</refname>
 <refpurpose>
     Release a PCI bar
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_release_region </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>int <parameter>bar</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     PCI device whose resources were previously reserved by pci_request_region
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bar</parameter></term>
   <listitem>
    <para>
     BAR to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases the PCI I/O and memory resources previously reserved by a
   successful call to pci_request_region.  Call this function only
   after all use of the PCI regions has ceased.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-request-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_request_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_request_region</refname>
 <refpurpose>
     Reserve PCI I/O and memory resource
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_request_region </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>int <parameter>bar</parameter></paramdef>
   <paramdef>const char * <parameter>res_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     PCI device whose resources are to be reserved
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bar</parameter></term>
   <listitem>
    <para>
     BAR to be reserved
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res_name</parameter></term>
   <listitem>
    <para>
     Name to be associated with resource
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Mark the PCI region associated with PCI device <parameter>pdev</parameter> BAR <parameter>bar</parameter> as
   being reserved by owner <parameter>res_name</parameter>.  Do not access any
   address inside the PCI regions unless this call returns
   successfully.
   </para><para>

   Returns 0 on success, or <constant>EBUSY</constant> on error.  A warning
   message is also printed on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-request-region-exclusive">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_request_region_exclusive</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_request_region_exclusive</refname>
 <refpurpose>
     Reserved PCI I/O and memory resource
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_request_region_exclusive </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>int <parameter>bar</parameter></paramdef>
   <paramdef>const char * <parameter>res_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     PCI device whose resources are to be reserved
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bar</parameter></term>
   <listitem>
    <para>
     BAR to be reserved
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res_name</parameter></term>
   <listitem>
    <para>
     Name to be associated with resource.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Mark the PCI region associated with PCI device <parameter>pdev</parameter> BR <parameter>bar</parameter> as
   being reserved by owner <parameter>res_name</parameter>.  Do not access any
   address inside the PCI regions unless this call returns
   successfully.
   </para><para>

   Returns 0 on success, or <constant>EBUSY</constant> on error.  A warning
   message is also printed on failure.
   </para><para>

   The key difference that _exclusive makes it that userspace is
   explicitly not allowed to map the resource via /dev/mem or
   sysfs.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-release-selected-regions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_release_selected_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_release_selected_regions</refname>
 <refpurpose>
     Release selected PCI I/O and memory resources
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_release_selected_regions </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>int <parameter>bars</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     PCI device whose resources were previously reserved
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bars</parameter></term>
   <listitem>
    <para>
     Bitmask of BARs to be released
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release selected PCI I/O and memory resources previously reserved.
   Call this function only after all use of the PCI regions has ceased.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-request-selected-regions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_request_selected_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_request_selected_regions</refname>
 <refpurpose>
     Reserve selected PCI I/O and memory resources
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_request_selected_regions </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>int <parameter>bars</parameter></paramdef>
   <paramdef>const char * <parameter>res_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     PCI device whose resources are to be reserved
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bars</parameter></term>
   <listitem>
    <para>
     Bitmask of BARs to be requested
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res_name</parameter></term>
   <listitem>
    <para>
     Name to be associated with resource
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pci-release-regions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_release_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_release_regions</refname>
 <refpurpose>
     Release reserved PCI I/O and memory resources
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_release_regions </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>
     PCI device whose resources were previously reserved by pci_request_regions
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases all PCI I/O and memory resources previously reserved by a
   successful call to pci_request_regions.  Call this function only
   after all use of the PCI regions has ceased.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-request-regions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_request_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_request_regions</refname>
 <refpurpose>
     Reserved PCI I/O and memory resources
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_request_regions </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>const char * <parameter>res_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     PCI device whose resources are to be reserved
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res_name</parameter></term>
   <listitem>
    <para>
     Name to be associated with resource.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Mark all PCI regions associated with PCI device <parameter>pdev</parameter> as
   being reserved by owner <parameter>res_name</parameter>.  Do not access any
   address inside the PCI regions unless this call returns
   successfully.
   </para><para>

   Returns 0 on success, or <constant>EBUSY</constant> on error.  A warning
   message is also printed on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-request-regions-exclusive">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_request_regions_exclusive</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_request_regions_exclusive</refname>
 <refpurpose>
     Reserved PCI I/O and memory resources
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_request_regions_exclusive </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>const char * <parameter>res_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     PCI device whose resources are to be reserved
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res_name</parameter></term>
   <listitem>
    <para>
     Name to be associated with resource.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Mark all PCI regions associated with PCI device <parameter>pdev</parameter> as
   being reserved by owner <parameter>res_name</parameter>.  Do not access any
   address inside the PCI regions unless this call returns
   successfully.
   </para><para>

   <function>pci_request_regions_exclusive</function> will mark the region so that
   /dev/mem and the sysfs MMIO access will not be allowed.
   </para><para>

   Returns 0 on success, or <constant>EBUSY</constant> on error.  A warning
   message is also printed on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-set-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_set_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_set_master</refname>
 <refpurpose>
     enables bus-mastering for device dev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_set_master </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device to enable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enables bus-mastering on the device and calls <function>pcibios_set_master</function>
   to do the needed arch specific settings.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-clear-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_clear_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_clear_master</refname>
 <refpurpose>
     disables bus-mastering for device dev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_clear_master </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pci-set-cacheline-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_set_cacheline_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_set_cacheline_size</refname>
 <refpurpose>
     ensure the CACHE_LINE_SIZE register is programmed
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_set_cacheline_size </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device for which MWI is to be enabled
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Helper function for pci_set_mwi.
   Originally copied from drivers/net/acenic.c.
   Copyright 1998-2001 by Jes Sorensen, &lt;jes<parameter>trained</parameter>-monkey.org&gt;.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   An appropriate -ERRNO error value on error, or zero for success.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-set-mwi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_set_mwi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_set_mwi</refname>
 <refpurpose>
     enables memory-write-invalidate PCI transaction
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_set_mwi </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device for which MWI is enabled
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enables the Memory-Write-Invalidate transaction in <constant>PCI_COMMAND</constant>.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   An appropriate -ERRNO error value on error, or zero for success.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-try-set-mwi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_try_set_mwi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_try_set_mwi</refname>
 <refpurpose>
     enables memory-write-invalidate PCI transaction
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_try_set_mwi </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device for which MWI is enabled
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enables the Memory-Write-Invalidate transaction in <constant>PCI_COMMAND</constant>.
   Callers are not required to check the return value.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   An appropriate -ERRNO error value on error, or zero for success.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-clear-mwi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_clear_mwi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_clear_mwi</refname>
 <refpurpose>
     disables Memory-Write-Invalidate for device dev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_clear_mwi </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Disables PCI Memory-Write-Invalidate transaction on the device
</para>
</refsect1>
</refentry>

<refentry id="API-pci-intx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_intx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_intx</refname>
 <refpurpose>
     enables/disables PCI INTx for device dev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_intx </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>int <parameter>enable</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     the PCI device to operate on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>enable</parameter></term>
   <listitem>
    <para>
     boolean: whether to enable or disable PCI INTx
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enables/disables PCI INTx for device dev
</para>
</refsect1>
</refentry>

<refentry id="API-pci-intx-mask-supported">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_intx_mask_supported</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_intx_mask_supported</refname>
 <refpurpose>
     probe for INTx masking support
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>pci_intx_mask_supported </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device to operate on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check if the device dev support INTx masking via the config space
   command word.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-check-and-mask-intx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_check_and_mask_intx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_check_and_mask_intx</refname>
 <refpurpose>
     mask INTx on pending interrupt
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>pci_check_and_mask_intx </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device to operate on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check if the device dev has its INTx line asserted, mask it and
   return true in that case. False is returned if not interrupt was
   pending.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-check-and-unmask-intx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_check_and_unmask_intx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_check_and_unmask_intx</refname>
 <refpurpose>
     unmask INTx if no interrupt is pending
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>pci_check_and_unmask_intx </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device to operate on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check if the device dev has its INTx line asserted, unmask it if not
   and return true. False is returned and the mask remains active if
   there was still an interrupt pending.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-msi-off">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_msi_off</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_msi_off</refname>
 <refpurpose>
     disables any MSI or MSI-X capabilities
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_msi_off </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device to operate on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If you want to use MSI, see <function>pci_enable_msi</function> and friends.
   This is a lower-level primitive that allows us to disable
   MSI operation at the device level.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-wait-for-pending-transaction">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_wait_for_pending_transaction</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_wait_for_pending_transaction</refname>
 <refpurpose>
     waits for pending transaction
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_wait_for_pending_transaction </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device to operate on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return 0 if transaction is pending 1 otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-reset-bridge-secondary-bus">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_reset_bridge_secondary_bus</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_reset_bridge_secondary_bus</refname>
 <refpurpose>
     Reset the secondary bus on a PCI bridge.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_reset_bridge_secondary_bus </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Bridge device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use the bridge control register to assert reset on the secondary bus.
   Devices on the secondary bus are left in power-on state.
</para>
</refsect1>
</refentry>

<refentry id="API---pci-reset-function">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__pci_reset_function</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__pci_reset_function</refname>
 <refpurpose>
     reset a PCI device function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__pci_reset_function </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Some devices allow an individual function to be reset without affecting
   other functions in the same device.  The PCI device must be responsive
   to PCI config space in order to use this function.
   </para><para>

   The device function is presumed to be unused when this function is called.
   Resetting the device will make the contents of PCI configuration space
   random, so any caller of this must be prepared to reinitialise the
   device including MSI, bus mastering, BARs, decoding IO and memory spaces,
   etc.
   </para><para>

   Returns 0 if the device function was successfully reset or negative if the
   device doesn't support resetting a single function.
</para>
</refsect1>
</refentry>

<refentry id="API---pci-reset-function-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__pci_reset_function_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__pci_reset_function_locked</refname>
 <refpurpose>
     reset a PCI device function while holding the <parameter>dev</parameter> mutex lock.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__pci_reset_function_locked </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Some devices allow an individual function to be reset without affecting
   other functions in the same device.  The PCI device must be responsive
   to PCI config space in order to use this function.
   </para><para>

   The device function is presumed to be unused and the caller is holding
   the device mutex lock when this function is called.
   Resetting the device will make the contents of PCI configuration space
   random, so any caller of this must be prepared to reinitialise the
   device including MSI, bus mastering, BARs, decoding IO and memory spaces,
   etc.
   </para><para>

   Returns 0 if the device function was successfully reset or negative if the
   device doesn't support resetting a single function.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-reset-function">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_reset_function</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_reset_function</refname>
 <refpurpose>
     quiesce and reset a PCI device function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_reset_function </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Some devices allow an individual function to be reset without affecting
   other functions in the same device.  The PCI device must be responsive
   to PCI config space in order to use this function.
   </para><para>

   This function does not just reset the PCI portion of a device, but
   clears all the state associated with the device.  This function differs
   from __pci_reset_function in that it saves and restores device state
   over the reset.
   </para><para>

   Returns 0 if the device function was successfully reset or negative if the
   device doesn't support resetting a single function.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-try-reset-function">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_try_reset_function</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_try_reset_function</refname>
 <refpurpose>
     quiesce and reset a PCI device function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_try_reset_function </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Same as above, except return -EAGAIN if unable to lock device.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-probe-reset-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_probe_reset_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_probe_reset_slot</refname>
 <refpurpose>
     probe whether a PCI slot can be reset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_probe_reset_slot </function></funcdef>
   <paramdef>struct pci_slot * <parameter>slot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>slot</parameter></term>
   <listitem>
    <para>
     PCI slot to probe
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return 0 if slot can be reset, negative if a slot reset is not supported.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-reset-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_reset_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_reset_slot</refname>
 <refpurpose>
     reset a PCI slot
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_reset_slot </function></funcdef>
   <paramdef>struct pci_slot * <parameter>slot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>slot</parameter></term>
   <listitem>
    <para>
     PCI slot to reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A PCI bus may host multiple slots, each slot may support a reset mechanism
   independent of other slots.  For instance, some slots may support slot power
   control.  In the case of a 1:1 bus to slot architecture, this function may
   wrap the bus reset to avoid spurious slot related events such as hotplug.
   Generally a slot reset should be attempted before a bus reset.  All of the
   function of the slot and any subordinate buses behind the slot are reset
   through this function.  PCI config space of all devices in the slot and
   behind the slot is saved before and restored after reset.
   </para><para>

   Return 0 on success, non-zero on error.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-try-reset-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_try_reset_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_try_reset_slot</refname>
 <refpurpose>
     Try to reset a PCI slot
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_try_reset_slot </function></funcdef>
   <paramdef>struct pci_slot * <parameter>slot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>slot</parameter></term>
   <listitem>
    <para>
     PCI slot to reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Same as above except return -EAGAIN if the slot cannot be locked
</para>
</refsect1>
</refentry>

<refentry id="API-pci-probe-reset-bus">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_probe_reset_bus</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_probe_reset_bus</refname>
 <refpurpose>
     probe whether a PCI bus can be reset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_probe_reset_bus </function></funcdef>
   <paramdef>struct pci_bus * <parameter>bus</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     PCI bus to probe
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return 0 if bus can be reset, negative if a bus reset is not supported.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-reset-bus">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_reset_bus</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_reset_bus</refname>
 <refpurpose>
     reset a PCI bus
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_reset_bus </function></funcdef>
   <paramdef>struct pci_bus * <parameter>bus</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     top level PCI bus to reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Do a bus reset on the given bus and any subordinate buses, saving
   and restoring state of all devices.
   </para><para>

   Return 0 on success, non-zero on error.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-try-reset-bus">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_try_reset_bus</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_try_reset_bus</refname>
 <refpurpose>
     Try to reset a PCI bus
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_try_reset_bus </function></funcdef>
   <paramdef>struct pci_bus * <parameter>bus</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     top level PCI bus to reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Same as above except return -EAGAIN if the bus cannot be locked
</para>
</refsect1>
</refentry>

<refentry id="API-pcix-get-max-mmrbc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcix_get_max_mmrbc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pcix_get_max_mmrbc</refname>
 <refpurpose>
     get PCI-X maximum designed memory read byte count
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pcix_get_max_mmrbc </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns mmrbc</title>
<para>
   maximum designed memory read count in bytes
   or appropriate error value.
</para>
</refsect1>
</refentry>

<refentry id="API-pcix-get-mmrbc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcix_get_mmrbc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pcix_get_mmrbc</refname>
 <refpurpose>
     get PCI-X maximum memory read byte count
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pcix_get_mmrbc </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns mmrbc</title>
<para>
   maximum memory read count in bytes
   or appropriate error value.
</para>
</refsect1>
</refentry>

<refentry id="API-pcix-set-mmrbc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcix_set_mmrbc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pcix_set_mmrbc</refname>
 <refpurpose>
     set PCI-X maximum memory read byte count
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pcix_set_mmrbc </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>mmrbc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mmrbc</parameter></term>
   <listitem>
    <para>
     maximum memory read count in bytes
     valid values are 512, 1024, 2048, 4096
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If possible sets maximum memory read byte count, some bridges have erratas
   that prevent this.
</para>
</refsect1>
</refentry>

<refentry id="API-pcie-get-readrq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcie_get_readrq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pcie_get_readrq</refname>
 <refpurpose>
     get PCI Express read request size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pcie_get_readrq </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns maximum memory read request in bytes
   or appropriate error value.
</para>
</refsect1>
</refentry>

<refentry id="API-pcie-set-readrq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcie_set_readrq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pcie_set_readrq</refname>
 <refpurpose>
     set PCI Express maximum memory read request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pcie_set_readrq </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>rq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     maximum memory read count in bytes
     valid values are 128, 256, 512, 1024, 2048, 4096
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If possible sets maximum memory read request in bytes
</para>
</refsect1>
</refentry>

<refentry id="API-pcie-get-mps">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcie_get_mps</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pcie_get_mps</refname>
 <refpurpose>
     get PCI Express maximum payload size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pcie_get_mps </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns maximum payload size in bytes
</para>
</refsect1>
</refentry>

<refentry id="API-pcie-set-mps">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcie_set_mps</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pcie_set_mps</refname>
 <refpurpose>
     set PCI Express maximum payload size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pcie_set_mps </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>mps</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mps</parameter></term>
   <listitem>
    <para>
     maximum payload size in bytes
     valid values are 128, 256, 512, 1024, 2048, 4096
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If possible sets maximum payload size
</para>
</refsect1>
</refentry>

<refentry id="API-pcie-get-minimum-link">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcie_get_minimum_link</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pcie_get_minimum_link</refname>
 <refpurpose>
     determine minimum link settings of a PCI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pcie_get_minimum_link </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>enum pci_bus_speed * <parameter>speed</parameter></paramdef>
   <paramdef>enum pcie_link_width * <parameter>width</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     PCI device to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>speed</parameter></term>
   <listitem>
    <para>
     storage for minimum speed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>width</parameter></term>
   <listitem>
    <para>
     storage for minimum width
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will walk up the PCI device chain and determine the minimum
   link width and speed of the device.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-select-bars">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_select_bars</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_select_bars</refname>
 <refpurpose>
     Make BAR mask from the type of resource
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_select_bars </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned long <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device for which BAR mask is made
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     resource type mask to be selected
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This helper routine makes bar mask from the type of resource.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/pci-driver.c -->
<refentry id="API-pci-add-dynid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_add_dynid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_add_dynid</refname>
 <refpurpose>
  add a new PCI device ID to this driver and re-probe devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_add_dynid </function></funcdef>
   <paramdef>struct pci_driver * <parameter>drv</parameter></paramdef>
   <paramdef>unsigned int <parameter>vendor</parameter></paramdef>
   <paramdef>unsigned int <parameter>device</parameter></paramdef>
   <paramdef>unsigned int <parameter>subvendor</parameter></paramdef>
   <paramdef>unsigned int <parameter>subdevice</parameter></paramdef>
   <paramdef>unsigned int <parameter>class</parameter></paramdef>
   <paramdef>unsigned int <parameter>class_mask</parameter></paramdef>
   <paramdef>unsigned long <parameter>driver_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     target pci driver
    </para>
   </listitem>
  </varlistentry>
  <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>subvendor</parameter></term>
   <listitem>
    <para>
     PCI subvendor ID
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>subdevice</parameter></term>
   <listitem>
    <para>
     PCI subdevice ID
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>class</parameter></term>
   <listitem>
    <para>
     PCI class
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>class_mask</parameter></term>
   <listitem>
    <para>
     PCI class mask
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>driver_data</parameter></term>
   <listitem>
    <para>
     private driver data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds a new dynamic pci device ID to this driver and causes the
   driver to probe for all devices again.  <parameter>drv</parameter> must have been
   registered prior to calling this function.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Does GFP_KERNEL allocation.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 on success, -errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-match-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_match_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_match_id</refname>
 <refpurpose>
     See if a pci device matches a given pci_id table
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct pci_device_id * <function>pci_match_id </function></funcdef>
   <paramdef>const struct pci_device_id * <parameter>ids</parameter></paramdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     array of PCI device id structures to search in
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device structure to match against.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Used by a driver to check whether a PCI device present in the
   system is in its list of supported devices.  Returns the matching
   pci_device_id structure or <constant>NULL</constant> if there is no match.
   </para><para>

   Deprecated, don't use this as it will not catch any dynamic ids
   that a driver might want to check for.
</para>
</refsect1>
</refentry>

<refentry id="API---pci-register-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__pci_register_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__pci_register_driver</refname>
 <refpurpose>
     register a new pci driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__pci_register_driver </function></funcdef>
   <paramdef>struct pci_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
   <paramdef>const char * <parameter>mod_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     the driver structure to register
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     owner module of drv
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mod_name</parameter></term>
   <listitem>
    <para>
     module name string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds the driver structure to the list of registered drivers.
   Returns a negative value on error, otherwise 0.
   If no error occurred, the driver remains registered even if
   no device was claimed during registration.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-unregister-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_unregister_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_unregister_driver</refname>
 <refpurpose>
     unregister a pci driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_unregister_driver </function></funcdef>
   <paramdef>struct pci_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     the driver structure to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Deletes the driver structure from the list of registered PCI drivers,
   gives it a chance to clean up by calling its <function>remove</function> function for
   each device it was responsible for, and marks those devices as
   driverless.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-dev-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_dev_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_dev_driver</refname>
 <refpurpose>
     get the pci_driver of a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_driver * <function>pci_dev_driver </function></funcdef>
   <paramdef>const struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the device to query
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the appropriate pci_driver structure or <constant>NULL</constant> if there is no
   registered driver for the device.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-dev-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_dev_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_dev_get</refname>
 <refpurpose>
     increments the reference count of the pci device structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_dev * <function>pci_dev_get </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the device being referenced
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each live reference to a device should be refcounted.
   </para><para>

   Drivers for PCI devices should normally record such references in
   their <function>probe</function> methods, when they bind to a device, and release
   them by calling <function>pci_dev_put</function>, in their <function>disconnect</function> methods.
   </para><para>

   A pointer to the device with the incremented reference counter is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-dev-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_dev_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_dev_put</refname>
 <refpurpose>
     release a use of the pci device structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_dev_put </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device that's been disconnected
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Must be called when a user of a device is finished with it.  When the last
   user of the device calls this function, the memory of the device is freed.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/remove.c -->
<refentry id="API-pci-stop-and-remove-bus-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_stop_and_remove_bus_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_stop_and_remove_bus_device</refname>
 <refpurpose>
  remove a PCI device and any children
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_stop_and_remove_bus_device </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the device to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove a PCI device from the device lists, informing the drivers
   that the device has been removed.  We also remove any subordinate
   buses and children in a depth-first manner.
   </para><para>

   For each device we remove, delete the device structure from the
   device lists, remove the /proc entry, and notify userspace
   (/sbin/hotplug).
</para>
</refsect1>
</refentry>

<!-- drivers/pci/search.c -->
<refentry id="API-pci-find-bus">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_bus</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_find_bus</refname>
 <refpurpose>
  locate PCI bus from a given domain and bus number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_bus * <function>pci_find_bus </function></funcdef>
   <paramdef>int <parameter>domain</parameter></paramdef>
   <paramdef>int <parameter>busnr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>domain</parameter></term>
   <listitem>
    <para>
     number of PCI domain to search
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>busnr</parameter></term>
   <listitem>
    <para>
     number of desired PCI bus
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a PCI bus number and domain number, the desired PCI bus is located
   in the global list of PCI buses.  If the bus is found, a pointer to its
   data structure is returned.  If no bus is found, <constant>NULL</constant> is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-find-next-bus">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_next_bus</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_find_next_bus</refname>
 <refpurpose>
     begin or continue searching for a PCI bus
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_bus * <function>pci_find_next_bus </function></funcdef>
   <paramdef>const struct pci_bus * <parameter>from</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     Previous PCI bus found, or <constant>NULL</constant> for new search.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterates through the list of known PCI buses.  A new search is
   initiated by passing <constant>NULL</constant> as the <parameter>from</parameter> argument.  Otherwise if
   <parameter>from</parameter> is not <constant>NULL</constant>, searches continue from next device on the
   global list.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-get-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_get_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_get_slot</refname>
 <refpurpose>
     locate PCI device for a given PCI slot
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_dev * <function>pci_get_slot </function></funcdef>
   <paramdef>struct pci_bus * <parameter>bus</parameter></paramdef>
   <paramdef>unsigned int <parameter>devfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     PCI bus on which desired PCI device resides
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devfn</parameter></term>
   <listitem>
    <para>
     encodes number of PCI slot in which the desired PCI
     device resides and the logical device number within that slot
     in case of multi-function devices.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a PCI bus and slot/function number, the desired PCI device
   is located in the list of PCI devices.
   If the device is found, its reference count is increased and this
   function returns a pointer to its data structure.  The caller must
   decrement the reference count by calling <function>pci_dev_put</function>.
   If no device is found, <constant>NULL</constant> is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-get-domain-bus-and-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_get_domain_bus_and_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_get_domain_bus_and_slot</refname>
 <refpurpose>
     locate PCI device for a given PCI domain (segment), bus, and slot
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_dev * <function>pci_get_domain_bus_and_slot </function></funcdef>
   <paramdef>int <parameter>domain</parameter></paramdef>
   <paramdef>unsigned int <parameter>bus</parameter></paramdef>
   <paramdef>unsigned int <parameter>devfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>domain</parameter></term>
   <listitem>
    <para>
     PCI domain/segment on which the PCI device resides.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     PCI bus on which desired PCI device resides
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devfn</parameter></term>
   <listitem>
    <para>
     encodes number of PCI slot in which the desired PCI device
     resides and the logical device number within that slot in case of
     multi-function devices.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a PCI domain, bus, and slot/function number, the desired PCI
   device is located in the list of PCI devices. If the device is
   found, its reference count is increased and this function returns a
   pointer to its data structure.  The caller must decrement the
   reference count by calling <function>pci_dev_put</function>.  If no device is found,
   <constant>NULL</constant> is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-get-subsys">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_get_subsys</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_get_subsys</refname>
 <refpurpose>
     begin or continue searching for a PCI device by vendor/subvendor/device/subdevice id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_dev * <function>pci_get_subsys </function></funcdef>
   <paramdef>unsigned int <parameter>vendor</parameter></paramdef>
   <paramdef>unsigned int <parameter>device</parameter></paramdef>
   <paramdef>unsigned int <parameter>ss_vendor</parameter></paramdef>
   <paramdef>unsigned int <parameter>ss_device</parameter></paramdef>
   <paramdef>struct pci_dev * <parameter>from</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vendor</parameter></term>
   <listitem>
    <para>
     PCI vendor id to match, or <constant>PCI_ANY_ID</constant> to match all vendor ids
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     PCI device id to match, or <constant>PCI_ANY_ID</constant> to match all device ids
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ss_vendor</parameter></term>
   <listitem>
    <para>
     PCI subsystem vendor id to match, or <constant>PCI_ANY_ID</constant> to match all vendor ids
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ss_device</parameter></term>
   <listitem>
    <para>
     PCI subsystem device id to match, or <constant>PCI_ANY_ID</constant> to match all device ids
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     Previous PCI device found in search, or <constant>NULL</constant> for new search.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterates through the list of known PCI devices.  If a PCI device is found
   with a matching <parameter>vendor</parameter>, <parameter>device</parameter>, <parameter>ss_vendor</parameter> and <parameter>ss_device</parameter>, a pointer to its
   device structure is returned, and the reference count to the device is
   incremented.  Otherwise, <constant>NULL</constant> is returned.  A new search is initiated by
   passing <constant>NULL</constant> as the <parameter>from</parameter> argument.  Otherwise if <parameter>from</parameter> is not <constant>NULL</constant>,
   searches continue from next device on the global list.
   The reference count for <parameter>from</parameter> is always decremented if it is not <constant>NULL</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-get-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_get_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_get_device</refname>
 <refpurpose>
     begin or continue searching for a PCI device by vendor/device id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_dev * <function>pci_get_device </function></funcdef>
   <paramdef>unsigned int <parameter>vendor</parameter></paramdef>
   <paramdef>unsigned int <parameter>device</parameter></paramdef>
   <paramdef>struct pci_dev * <parameter>from</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vendor</parameter></term>
   <listitem>
    <para>
     PCI vendor id to match, or <constant>PCI_ANY_ID</constant> to match all vendor ids
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     PCI device id to match, or <constant>PCI_ANY_ID</constant> to match all device ids
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     Previous PCI device found in search, or <constant>NULL</constant> for new search.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterates through the list of known PCI devices.  If a PCI device is
   found with a matching <parameter>vendor</parameter> and <parameter>device</parameter>, the reference count to the
   device is incremented and a pointer to its device structure is returned.
   Otherwise, <constant>NULL</constant> is returned.  A new search is initiated by passing <constant>NULL</constant>
   as the <parameter>from</parameter> argument.  Otherwise if <parameter>from</parameter> is not <constant>NULL</constant>, searches continue
   from next device on the global list.  The reference count for <parameter>from</parameter> is
   always decremented if it is not <constant>NULL</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-get-class">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_get_class</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_get_class</refname>
 <refpurpose>
     begin or continue searching for a PCI device by class
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_dev * <function>pci_get_class </function></funcdef>
   <paramdef>unsigned int <parameter>class</parameter></paramdef>
   <paramdef>struct pci_dev * <parameter>from</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>class</parameter></term>
   <listitem>
    <para>
     search for a PCI device with this class designation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     Previous PCI device found in search, or <constant>NULL</constant> for new search.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterates through the list of known PCI devices.  If a PCI device is
   found with a matching <parameter>class</parameter>, the reference count to the device is
   incremented and a pointer to its device structure is returned.
   Otherwise, <constant>NULL</constant> is returned.
   A new search is initiated by passing <constant>NULL</constant> as the <parameter>from</parameter> argument.
   Otherwise if <parameter>from</parameter> is not <constant>NULL</constant>, searches continue from next device
   on the global list.  The reference count for <parameter>from</parameter> is always decremented
   if it is not <constant>NULL</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-dev-present">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_dev_present</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_dev_present</refname>
 <refpurpose>
     Returns 1 if device matching the device list is present, 0 if not.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_dev_present </function></funcdef>
   <paramdef>const struct pci_device_id * <parameter>ids</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     A pointer to a null terminated list of struct pci_device_id structures
     that describe the type of PCI device the caller is trying to find.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Obvious fact</title>
<para>
   You do not have a reference to any device that might be found
   by this function, so if that device is removed from the system right after
   this function is finished, the value will be stale.  Use this function to
   find devices that are usually built into a system, or for a general hint as
   to if another device happens to be present at this specific moment in time.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/msi.c -->
<refentry id="API-pci-msi-vec-count">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_msi_vec_count</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_msi_vec_count</refname>
 <refpurpose>
  Return the number of MSI vectors a device can send
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_msi_vec_count </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to report about
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function returns the number of MSI vectors a device requested via
   Multiple Message Capable register. It returns a negative errno if the
   device is not capable sending MSI interrupts. Otherwise, the call succeeds
   and returns a power of two, up to a maximum of 2^5 (32), according to the
   MSI specification.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-msix-vec-count">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_msix_vec_count</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_msix_vec_count</refname>
 <refpurpose>
     return the number of device's MSI-X table entries
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_msix_vec_count </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the pci_dev data structure of MSI-X device function
     This function returns the number of device's MSI-X table entries and
     therefore the number of MSI-X vectors device is capable of sending.
     It returns a negative errno if the device is not capable of sending MSI-X
     interrupts.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pci-enable-msix">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_msix</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_enable_msix</refname>
 <refpurpose>
     configure device's MSI-X capability structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_enable_msix </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>struct msix_entry * <parameter>entries</parameter></paramdef>
   <paramdef>int <parameter>nvec</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the pci_dev data structure of MSI-X device function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>entries</parameter></term>
   <listitem>
    <para>
     pointer to an array of MSI-X entries
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nvec</parameter></term>
   <listitem>
    <para>
     number of MSI-X irqs requested for allocation by device driver
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Setup the MSI-X capability structure of device function with the number
   of requested irqs upon its software driver call to request for
   MSI-X mode enabled on its hardware device function. A return of zero
   indicates the successful configuration of MSI-X capability structure
   with new allocated MSI-X irqs. A return of &lt; 0 indicates a failure.
   Or a return of &gt; 0 indicates that driver request is exceeding the number
   of irqs or MSI-X vectors available. Driver should use the returned value to
   re-send its request.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-msi-enabled">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_msi_enabled</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_msi_enabled</refname>
 <refpurpose>
     is MSI enabled?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_msi_enabled </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 true if MSI has not been disabled by the command-line option
   pci=nomsi.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-enable-msi-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_msi_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_enable_msi_range</refname>
 <refpurpose>
     configure device's MSI capability structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_enable_msi_range </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>minvec</parameter></paramdef>
   <paramdef>int <parameter>maxvec</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to configure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>minvec</parameter></term>
   <listitem>
    <para>
     minimal number of interrupts to configure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maxvec</parameter></term>
   <listitem>
    <para>
     maximum number of interrupts to configure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function tries to allocate a maximum possible number of interrupts in a
   range between <parameter>minvec</parameter> and <parameter>maxvec</parameter>. It returns a negative errno if an error
   occurs. If it succeeds, it returns the actual number of interrupts allocated
   and updates the <parameter>dev</parameter>'s irq member to the lowest new interrupt number;
   the other interrupt numbers allocated to this device are consecutive.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-enable-msix-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_msix_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_enable_msix_range</refname>
 <refpurpose>
     configure device's MSI-X capability structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_enable_msix_range </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>struct msix_entry * <parameter>entries</parameter></paramdef>
   <paramdef>int <parameter>minvec</parameter></paramdef>
   <paramdef>int <parameter>maxvec</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the pci_dev data structure of MSI-X device function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>entries</parameter></term>
   <listitem>
    <para>
     pointer to an array of MSI-X entries
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>minvec</parameter></term>
   <listitem>
    <para>
     minimum number of MSI-X irqs requested
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maxvec</parameter></term>
   <listitem>
    <para>
     maximum number of MSI-X irqs requested
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Setup the MSI-X capability structure of device function with a maximum
   possible number of interrupts in the range between <parameter>minvec</parameter> and <parameter>maxvec</parameter>
   upon its software driver call to request for MSI-X mode enabled on its
   hardware device function. It returns a negative errno if an error occurs.
   If it succeeds, it returns the actual number of interrupts allocated and
   indicates the successful configuration of MSI-X capability structure
   with new allocated MSI-X interrupts.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/bus.c -->
<refentry id="API-pci-bus-alloc-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_bus_alloc_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_bus_alloc_resource</refname>
 <refpurpose>
  allocate a resource from a parent bus
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_bus_alloc_resource </function></funcdef>
   <paramdef>struct pci_bus * <parameter>bus</parameter></paramdef>
   <paramdef>struct resource * <parameter>res</parameter></paramdef>
   <paramdef>resource_size_t <parameter>size</parameter></paramdef>
   <paramdef>resource_size_t <parameter>align</parameter></paramdef>
   <paramdef>resource_size_t <parameter>min</parameter></paramdef>
   <paramdef>unsigned long <parameter>type_mask</parameter></paramdef>
   <paramdef>resource_size_t (*<parameter>alignf</parameter>)
     <funcparams>void *, 					  const struct resource *, 					  resource_size_t, 					  resource_size_t</funcparams></paramdef>
   <paramdef>void * <parameter>alignf_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     PCI bus
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     resource to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of resource to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>align</parameter></term>
   <listitem>
    <para>
     alignment of resource to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     minimum /proc/iomem address to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type_mask</parameter></term>
   <listitem>
    <para>
     IORESOURCE_* type flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alignf</parameter></term>
   <listitem>
    <para>
     resource alignment function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alignf_data</parameter></term>
   <listitem>
    <para>
     data argument for resource alignment function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given the PCI bus a device resides on, the size, minimum address,
   alignment and type, try to find an acceptable resource allocation
   for a specific device resource.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-bus-add-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_bus_add_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_bus_add_device</refname>
 <refpurpose>
     start driver for a single device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_bus_add_device </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This adds add sysfs entries and start device drivers
</para>
</refsect1>
</refentry>

<refentry id="API-pci-bus-add-devices">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_bus_add_devices</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_bus_add_devices</refname>
 <refpurpose>
     start driver for PCI devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_bus_add_devices </function></funcdef>
   <paramdef>const struct pci_bus * <parameter>bus</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     bus to check for new devices
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Start driver for PCI devices and add some sysfs entries.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/access.c -->
<refentry id="API-pci-bus-set-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_bus_set_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_bus_set_ops</refname>
 <refpurpose>
  Set raw operations of pci bus
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_ops * <function>pci_bus_set_ops </function></funcdef>
   <paramdef>struct pci_bus * <parameter>bus</parameter></paramdef>
   <paramdef>struct pci_ops * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     pci bus struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     new raw operations
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return previous raw operations
</para>
</refsect1>
</refentry>

<refentry id="API-pci-read-vpd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_read_vpd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_read_vpd</refname>
 <refpurpose>
     Read one entry from Vital Product Data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>pci_read_vpd </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>loff_t <parameter>pos</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
   <paramdef>void * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pci device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     offset in vpd space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of bytes to read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     pointer to where to store result
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pci-write-vpd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_write_vpd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_write_vpd</refname>
 <refpurpose>
     Write entry to Vital Product Data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>pci_write_vpd </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>loff_t <parameter>pos</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
   <paramdef>const void * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pci device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     offset in vpd space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of bytes to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     buffer containing write data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pci-cfg-access-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_cfg_access_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_cfg_access_lock</refname>
 <refpurpose>
     Lock PCI config reads/writes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_cfg_access_lock </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pci device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When access is locked, any userspace reads or writes to config
   space and concurrent lock requests will sleep until access is
   allowed via pci_cfg_access_unlocked again.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-cfg-access-trylock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_cfg_access_trylock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_cfg_access_trylock</refname>
 <refpurpose>
     try to lock PCI config reads/writes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>pci_cfg_access_trylock </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pci device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Same as pci_cfg_access_lock, but will return 0 if access is
   already locked, 1 otherwise. This function can be used from
   atomic contexts.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-cfg-access-unlock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_cfg_access_unlock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_cfg_access_unlock</refname>
 <refpurpose>
     Unlock PCI config reads/writes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_cfg_access_unlock </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pci device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function allows PCI config accesses to resume.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/irq.c -->
<refentry id="API-pci-lost-interrupt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_lost_interrupt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_lost_interrupt</refname>
 <refpurpose>
  reports a lost PCI interrupt
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>enum pci_lost_interrupt_reason <function>pci_lost_interrupt </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>
     device whose interrupt is lost
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The primary function of this routine is to report a lost interrupt
   in a standard way which users can recognise (instead of blaming the
   driver).
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   a suggestion for fixing it (although the driver is not required to
   act on this).
</para>
</refsect1>
</refentry>

<!-- drivers/pci/htirq.c -->
<refentry id="API---ht-create-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__ht_create_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__ht_create_irq</refname>
 <refpurpose>
  create an irq and attach it to a device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__ht_create_irq </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>idx</parameter></paramdef>
   <paramdef>ht_irq_update_t * <parameter>update</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     The hypertransport device to find the irq capability on.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>idx</parameter></term>
   <listitem>
    <para>
     Which of the possible irqs to attach to.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>update</parameter></term>
   <listitem>
    <para>
     Function to be called when changing the htirq message
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The irq number of the new irq or a negative error value is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-ht-create-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ht_create_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ht_create_irq</refname>
 <refpurpose>
     create an irq and attach it to a device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ht_create_irq </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     The hypertransport device to find the irq capability on.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>idx</parameter></term>
   <listitem>
    <para>
     Which of the possible irqs to attach to.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   ht_create_irq needs to be called for all hypertransport devices
   that generate irqs.
   </para><para>

   The irq number of the new irq or a negative error value is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-ht-destroy-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ht_destroy_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ht_destroy_irq</refname>
 <refpurpose>
     destroy an irq created with ht_create_irq
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ht_destroy_irq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     irq to be destroyed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This reverses ht_create_irq removing the specified irq from
   existence.  The irq should be free before this happens.
</para>
</refsect1>
</refentry>

<!-- FIXME: Removed for now since no structured comments in source
X!Edrivers/pci/hotplug.c
-->
<!-- drivers/pci/probe.c -->
<refentry id="API-pci-scan-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_scan_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_scan_slot</refname>
 <refpurpose>
  scan a PCI slot on a bus for devices.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_scan_slot </function></funcdef>
   <paramdef>struct pci_bus * <parameter>bus</parameter></paramdef>
   <paramdef>int <parameter>devfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     PCI bus to scan
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devfn</parameter></term>
   <listitem>
    <para>
     slot number to scan (must have zero function.)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Scan a PCI slot on the specified PCI bus for devices, adding
   discovered devices to the <parameter>bus</parameter>-&gt;devices list.  New devices
   will not have is_added set.
   </para><para>

   Returns the number of new devices found.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-rescan-bus">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_rescan_bus</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_rescan_bus</refname>
 <refpurpose>
     scan a PCI bus for devices.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>pci_rescan_bus </function></funcdef>
   <paramdef>struct pci_bus * <parameter>bus</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     PCI bus to scan
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Scan a PCI bus and child buses for new devices, adds them,
   and enables them.
   </para><para>

   Returns the max number of subordinate bus discovered.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/slot.c -->
<refentry id="API-pci-create-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_create_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_create_slot</refname>
 <refpurpose>
  create or increment refcount for physical PCI slot
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_slot * <function>pci_create_slot </function></funcdef>
   <paramdef>struct pci_bus * <parameter>parent</parameter></paramdef>
   <paramdef>int <parameter>slot_nr</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct hotplug_slot * <parameter>hotplug</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     struct pci_bus of parent bridge
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>slot_nr</parameter></term>
   <listitem>
    <para>
     PCI_SLOT(pci_dev-&gt;devfn) or -1 for placeholder
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     user visible string presented in /sys/bus/pci/slots/&lt;name&gt;
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hotplug</parameter></term>
   <listitem>
    <para>
     set if caller is hotplug driver, NULL otherwise
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   PCI slots have first class attributes such as address, speed, width,
   and a <structname>struct pci_slot</structname> is used to manage them. This interface will
   either return a new <structname>struct pci_slot</structname> to the caller, or if the pci_slot
   already exists, its refcount will be incremented.
   </para><para>

   Slots are uniquely identified by a <parameter>pci_bus</parameter>, <parameter>slot_nr</parameter> tuple.
   </para><para>

   There are known platforms with broken firmware that assign the same
   name to multiple slots. Workaround these broken platforms by renaming
   the slots on behalf of the caller. If firmware assigns name N to
</para>
</refsect1>
<refsect1>
<title>multiple slots</title>
<para>
   </para><para>

   The first slot is assigned N
   The second slot is assigned N-1
   The third slot is assigned N-2
   etc.
</para>
</refsect1>
<refsect1>
<title>Placeholder slots</title>
<para>
   In most cases, <parameter>pci_bus</parameter>, <parameter>slot_nr</parameter> will be sufficient to uniquely identify
   a slot. There is one notable exception - pSeries (rpaphp), where the
   <parameter>slot_nr</parameter> cannot be determined until a device is actually inserted into
   the slot. In this scenario, the caller may pass -1 for <parameter>slot_nr</parameter>.
   </para><para>

   The following semantics are imposed when the caller passes <parameter>slot_nr</parameter> ==
   -1. First, we no longer check for an existing <constant>struct</constant> pci_slot, as there
   may be many slots with <parameter>slot_nr</parameter> of -1.  The other change in semantics is
   user-visible, which is the 'address' parameter presented in sysfs will
</para>
</refsect1>
<refsect1>
<title>consist solely of a dddd</title>
<para>
   bb tuple, where dddd is the PCI domain of the
   <constant>struct</constant> pci_bus and bb is the bus number. In other words, the devfn of
   the 'placeholder' slot will not be displayed.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-destroy-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_destroy_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_destroy_slot</refname>
 <refpurpose>
     decrement refcount for physical PCI slot
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_destroy_slot </function></funcdef>
   <paramdef>struct pci_slot * <parameter>slot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>slot</parameter></term>
   <listitem>
    <para>
     struct pci_slot to decrement
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <constant>struct</constant> pci_slot is refcounted, so destroying them is really easy; we
   just call kobject_put on its kobj and let our release methods do the
   rest.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-hp-create-module-link">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_hp_create_module_link</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_hp_create_module_link</refname>
 <refpurpose>
     create symbolic link to the hotplug driver module.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_hp_create_module_link </function></funcdef>
   <paramdef>struct pci_slot * <parameter>pci_slot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pci_slot</parameter></term>
   <listitem>
    <para>
     struct pci_slot
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Helper function for pci_hotplug_core.c to create symbolic link to
   the hotplug driver module.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-hp-remove-module-link">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_hp_remove_module_link</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_hp_remove_module_link</refname>
 <refpurpose>
     remove symbolic link to the hotplug driver module.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_hp_remove_module_link </function></funcdef>
   <paramdef>struct pci_slot * <parameter>pci_slot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pci_slot</parameter></term>
   <listitem>
    <para>
     struct pci_slot
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Helper function for pci_hotplug_core.c to remove symbolic link to
   the hotplug driver module.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/rom.c -->
<refentry id="API-pci-enable-rom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_rom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_enable_rom</refname>
 <refpurpose>
  enable ROM decoding for a PCI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_enable_rom </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>
     PCI device to enable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enable ROM decoding on <parameter>dev</parameter>.  This involves simply turning on the last
   bit of the PCI ROM BAR.  Note that some cards may share address decoders
   between the ROM and other resources, so enabling it may disable access
   to MMIO registers or other card memory.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-disable-rom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_disable_rom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_disable_rom</refname>
 <refpurpose>
     disable ROM decoding for a PCI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_disable_rom </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>
     PCI device to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Disable ROM decoding on a PCI device by turning off the last bit in the
   ROM BAR.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-map-rom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_map_rom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_map_rom</refname>
 <refpurpose>
     map a PCI ROM to kernel space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __iomem * <function>pci_map_rom </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</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>
     pointer to pci device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     pointer to receive size of pci window over ROM
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   kernel virtual pointer to image of ROM
   </para><para>

   Map a PCI ROM into kernel space. If ROM is boot video ROM,
   the shadow BIOS copy will be returned instead of the
   actual ROM.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-unmap-rom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_unmap_rom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_unmap_rom</refname>
 <refpurpose>
     unmap the ROM from kernel space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_unmap_rom </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>void __iomem * <parameter>rom</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     pointer to pci device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rom</parameter></term>
   <listitem>
    <para>
     virtual address of the previous mapping
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove a mapping of a previously mapped ROM
</para>
</refsect1>
</refentry>

<refentry id="API-pci-platform-rom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_platform_rom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_platform_rom</refname>
 <refpurpose>
     provides a pointer to any ROM image provided by the platform
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __iomem * <function>pci_platform_rom </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</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>
     pointer to pci device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     pointer to receive size of pci window over ROM
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/pci/iov.c -->
<refentry id="API-pci-enable-sriov">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_sriov</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_enable_sriov</refname>
 <refpurpose>
  enable the SR-IOV capability
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_enable_sriov </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>nr_virtfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_virtfn</parameter></term>
   <listitem>
    <para>
     number of virtual functions to enable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success, or negative on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-disable-sriov">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_disable_sriov</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_disable_sriov</refname>
 <refpurpose>
     disable the SR-IOV capability
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_disable_sriov </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pci-num-vf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_num_vf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_num_vf</refname>
 <refpurpose>
     return number of VFs associated with a PF device_release_driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_num_vf </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns number of VFs, or 0 if SR-IOV is not enabled.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-vfs-assigned">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_vfs_assigned</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_vfs_assigned</refname>
 <refpurpose>
     returns number of VFs are assigned to a guest
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_vfs_assigned </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns number of VFs belonging to this device that are assigned to a guest.
   If device is not a physical function returns 0.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-sriov-set-totalvfs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_sriov_set_totalvfs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_sriov_set_totalvfs</refname>
 <refpurpose>
     - reduce the TotalVFs available
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_sriov_set_totalvfs </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>u16 <parameter>numvfs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI PF device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>numvfs</parameter></term>
   <listitem>
    <para>
     number that should be used for TotalVFs supported
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Should be called from PF driver's probe routine with
   device's mutex held.
   </para><para>

   Returns 0 if PF is an SRIOV-capable device and
   value of numvfs valid. If not a PF return -ENOSYS;
   if numvfs is invalid return -EINVAL;
   if VFs already enabled, return -EBUSY.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-sriov-get-totalvfs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_sriov_get_totalvfs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_sriov_get_totalvfs</refname>
 <refpurpose>
     - get total VFs supported on this device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_sriov_get_totalvfs </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the PCI PF device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   For a PCIe device with SRIOV support, return the PCIe
   SRIOV capability value of TotalVFs or the value of driver_max_VFs
   if the driver reduced it.  Otherwise 0.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/pci-sysfs.c -->
<refentry id="API-pci-read-legacy-io">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_read_legacy_io</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_read_legacy_io</refname>
 <refpurpose>
  read byte(s) from legacy I/O port space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>pci_read_legacy_io </function></funcdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>struct bin_attribute * <parameter>bin_attr</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>loff_t <parameter>off</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     open sysfs file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     kobject corresponding to file to read from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bin_attr</parameter></term>
   <listitem>
    <para>
     struct bin_attribute for this file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     buffer to store results
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>off</parameter></term>
   <listitem>
    <para>
     offset into legacy I/O port space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of bytes to read
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reads 1, 2, or 4 bytes from legacy I/O port space using an arch specific
   callback routine (pci_legacy_read).
</para>
</refsect1>
</refentry>

<refentry id="API-pci-write-legacy-io">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_write_legacy_io</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_write_legacy_io</refname>
 <refpurpose>
     write byte(s) to legacy I/O port space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>pci_write_legacy_io </function></funcdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>struct bin_attribute * <parameter>bin_attr</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>loff_t <parameter>off</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     open sysfs file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     kobject corresponding to file to read from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bin_attr</parameter></term>
   <listitem>
    <para>
     struct bin_attribute for this file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     buffer containing value to be written
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>off</parameter></term>
   <listitem>
    <para>
     offset into legacy I/O port space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of bytes to write
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Writes 1, 2, or 4 bytes from legacy I/O port space using an arch specific
   callback routine (pci_legacy_write).
</para>
</refsect1>
</refentry>

<refentry id="API-pci-mmap-legacy-mem">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_mmap_legacy_mem</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_mmap_legacy_mem</refname>
 <refpurpose>
     map legacy PCI memory into user memory space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_mmap_legacy_mem </function></funcdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>struct bin_attribute * <parameter>attr</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     open sysfs file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     kobject corresponding to device to be mapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     struct bin_attribute for this file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     struct vm_area_struct passed to mmap
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Uses an arch specific callback, pci_mmap_legacy_mem_page_range, to mmap
   legacy memory space (first meg of bus space) into application virtual
   memory space.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-mmap-legacy-io">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_mmap_legacy_io</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_mmap_legacy_io</refname>
 <refpurpose>
     map legacy PCI IO into user memory space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_mmap_legacy_io </function></funcdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>struct bin_attribute * <parameter>attr</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     open sysfs file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     kobject corresponding to device to be mapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     struct bin_attribute for this file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     struct vm_area_struct passed to mmap
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Uses an arch specific callback, pci_mmap_legacy_io_page_range, to mmap
   legacy IO space (first meg of bus space) into application virtual
   memory space. Returns -ENOSYS if the operation isn't supported
</para>
</refsect1>
</refentry>

<refentry id="API-pci-adjust-legacy-attr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_adjust_legacy_attr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_adjust_legacy_attr</refname>
 <refpurpose>
     adjustment of legacy file attributes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_adjust_legacy_attr </function></funcdef>
   <paramdef>struct pci_bus * <parameter>b</parameter></paramdef>
   <paramdef>enum pci_mmap_state <parameter>mmap_type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>b</parameter></term>
   <listitem>
    <para>
     bus to create files under
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mmap_type</parameter></term>
   <listitem>
    <para>
     I/O port or memory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Stub implementation. Can be overridden by arch if necessary.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-create-legacy-files">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_create_legacy_files</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_create_legacy_files</refname>
 <refpurpose>
     create legacy I/O port and memory files
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_create_legacy_files </function></funcdef>
   <paramdef>struct pci_bus * <parameter>b</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>b</parameter></term>
   <listitem>
    <para>
     bus to create files under
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Some platforms allow access to legacy I/O port and ISA memory space on
   a per-bus basis.  This routine creates the files and ties them into
   their associated read, write and mmap files from pci-sysfs.c
   </para><para>

   On error unwind, but don't propagate the error to the caller
   as it is ok to set up the PCI bus without these files.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-mmap-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_mmap_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_mmap_resource</refname>
 <refpurpose>
     map a PCI resource into user memory space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_mmap_resource </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>struct bin_attribute * <parameter>attr</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
   <paramdef>int <parameter>write_combine</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     kobject for mapping
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     struct bin_attribute for the file being mapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     struct vm_area_struct passed into the mmap
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>write_combine</parameter></term>
   <listitem>
    <para>
     1 for write_combine mapping
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use the regular PCI mapping routines to map a PCI resource into userspace.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-remove-resource-files">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_remove_resource_files</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_remove_resource_files</refname>
 <refpurpose>
     cleanup resource files
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_remove_resource_files </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>
     dev to cleanup
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If we created resource files for <parameter>pdev</parameter>, remove them from sysfs and
   free their resources.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-create-resource-files">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_create_resource_files</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_create_resource_files</refname>
 <refpurpose>
     create resource files in sysfs for <parameter>dev</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_create_resource_files </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>
     dev in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Walk the resources in <parameter>pdev</parameter> creating files for each resource available.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-write-rom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_write_rom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_write_rom</refname>
 <refpurpose>
     used to enable access to the PCI ROM display
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>pci_write_rom </function></funcdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>struct bin_attribute * <parameter>bin_attr</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>loff_t <parameter>off</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     sysfs file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     kernel object handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bin_attr</parameter></term>
   <listitem>
    <para>
     struct bin_attribute for this file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     user input
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>off</parameter></term>
   <listitem>
    <para>
     file offset
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of byte in input
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   writing anything except 0 enables it
</para>
</refsect1>
</refentry>

<refentry id="API-pci-read-rom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_read_rom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_read_rom</refname>
 <refpurpose>
     read a PCI ROM
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>pci_read_rom </function></funcdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>struct bin_attribute * <parameter>bin_attr</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>loff_t <parameter>off</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     sysfs file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     kernel object handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bin_attr</parameter></term>
   <listitem>
    <para>
     struct bin_attribute for this file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     where to put the data we read from the ROM
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>off</parameter></term>
   <listitem>
    <para>
     file offset
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of bytes to read
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Put <parameter>count</parameter> bytes starting at <parameter>off</parameter> into <parameter>buf</parameter> from the ROM in the PCI
   device corresponding to <parameter>kobj</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-remove-sysfs-dev-files">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_remove_sysfs_dev_files</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_remove_sysfs_dev_files</refname>
 <refpurpose>
     cleanup PCI specific sysfs files
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_remove_sysfs_dev_files </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>
     device whose entries we should free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Cleanup when <parameter>pdev</parameter> is removed from sysfs.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>PCI Hotplug Support Library</title>
<!-- drivers/pci/hotplug/pci_hotplug_core.c -->
<refentry id="API---pci-hp-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__pci_hp_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__pci_hp_register</refname>
 <refpurpose>
  register a hotplug_slot with the PCI hotplug subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__pci_hp_register </function></funcdef>
   <paramdef>struct hotplug_slot * <parameter>slot</parameter></paramdef>
   <paramdef>struct pci_bus * <parameter>bus</parameter></paramdef>
   <paramdef>int <parameter>devnr</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
   <paramdef>const char * <parameter>mod_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>slot</parameter></term>
   <listitem>
    <para>
     pointer to the <structname>struct hotplug_slot</structname> to register
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     bus this slot is on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devnr</parameter></term>
   <listitem>
    <para>
     device number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name registered with kobject core
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     caller module owner
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mod_name</parameter></term>
   <listitem>
    <para>
     caller module name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers a hotplug slot with the pci hotplug subsystem, which will allow
   userspace interaction to the slot.
   </para><para>

   Returns 0 if successful, anything else for an error.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-hp-deregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_hp_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_hp_deregister</refname>
 <refpurpose>
     deregister a hotplug_slot with the PCI hotplug subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_hp_deregister </function></funcdef>
   <paramdef>struct hotplug_slot * <parameter>hotplug</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hotplug</parameter></term>
   <listitem>
    <para>
     pointer to the <structname>struct hotplug_slot</structname> to deregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The <parameter>slot</parameter> must have been registered with the pci hotplug subsystem
   previously with a call to <function>pci_hp_register</function>.
   </para><para>

   Returns 0 if successful, anything else for an error.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-hp-change-slot-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_hp_change_slot_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_hp_change_slot_info</refname>
 <refpurpose>
     changes the slot's information structure in the core
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_hp_change_slot_info </function></funcdef>
   <paramdef>struct hotplug_slot * <parameter>hotplug</parameter></paramdef>
   <paramdef>struct hotplug_slot_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hotplug</parameter></term>
   <listitem>
    <para>
     pointer to the slot whose info has changed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     pointer to the info copy into the slot's info structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <parameter>slot</parameter> must have been registered with the pci
   hotplug subsystem previously with a call to <function>pci_hp_register</function>.
   </para><para>

   Returns 0 if successful, anything else for an error.
</para>
</refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="firmware">
     <title>Firmware Interfaces</title>
     <sect1><title>DMI Interfaces</title>
<!-- drivers/firmware/dmi_scan.c -->
<refentry id="API-dmi-check-system">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_check_system</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmi_check_system</refname>
 <refpurpose>
  check system DMI data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dmi_check_system </function></funcdef>
   <paramdef>const struct dmi_system_id * <parameter>list</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     array of dmi_system_id structures to match against
     All non-null elements of the list must match
     their slot's (field index's) data (i.e., each
     list string must be a substring of the specified
     DMI slot's string data) to be considered a
     successful match.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Walk the blacklist table running matching functions until someone
   returns non zero or we hit the end. Callback function is called for
   each successful match. Returns the number of matches.
</para>
</refsect1>
</refentry>

<refentry id="API-dmi-first-match">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_first_match</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmi_first_match</refname>
 <refpurpose>
     find dmi_system_id structure matching system DMI data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct dmi_system_id * <function>dmi_first_match </function></funcdef>
   <paramdef>const struct dmi_system_id * <parameter>list</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     array of dmi_system_id structures to match against
     All non-null elements of the list must match
     their slot's (field index's) data (i.e., each
     list string must be a substring of the specified
     DMI slot's string data) to be considered a
     successful match.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Walk the blacklist table until the first match is found.  Return the
   pointer to the matching entry or NULL if there's no match.
</para>
</refsect1>
</refentry>

<refentry id="API-dmi-get-system-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_get_system_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmi_get_system_info</refname>
 <refpurpose>
     return DMI data value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>dmi_get_system_info </function></funcdef>
   <paramdef>int <parameter>field</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>field</parameter></term>
   <listitem>
    <para>
     data index (see enum dmi_field)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns one DMI data value, can be used to perform
   complex DMI data checks.
</para>
</refsect1>
</refentry>

<refentry id="API-dmi-name-in-vendors">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_name_in_vendors</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmi_name_in_vendors</refname>
 <refpurpose>
     Check if string is in the DMI system or board vendor name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dmi_name_in_vendors </function></funcdef>
   <paramdef>const char * <parameter>str</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>str</parameter></term>
   <listitem>
    <para>
     Case sensitive Name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-dmi-find-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_find_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmi_find_device</refname>
 <refpurpose>
     find onboard device by type/name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct dmi_device * <function>dmi_find_device </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>const struct dmi_device * <parameter>from</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     device type or <constant>DMI_DEV_TYPE_ANY</constant> to match all device types
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     device name string or <constant>NULL</constant> to match all
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     previous device found in search, or <constant>NULL</constant> for new search.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterates through the list of known onboard devices. If a device is
   found with a matching <parameter>vendor</parameter> and <parameter>device</parameter>, a pointer to its device
   structure is returned.  Otherwise, <constant>NULL</constant> is returned.
   A new search is initiated by passing <constant>NULL</constant> as the <parameter>from</parameter> argument.
   If <parameter>from</parameter> is not <constant>NULL</constant>, searches continue from next device.
</para>
</refsect1>
</refentry>

<refentry id="API-dmi-get-date">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_get_date</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmi_get_date</refname>
 <refpurpose>
     parse a DMI date
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>dmi_get_date </function></funcdef>
   <paramdef>int <parameter>field</parameter></paramdef>
   <paramdef>int * <parameter>yearp</parameter></paramdef>
   <paramdef>int * <parameter>monthp</parameter></paramdef>
   <paramdef>int * <parameter>dayp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>field</parameter></term>
   <listitem>
    <para>
     data index (see enum dmi_field)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>yearp</parameter></term>
   <listitem>
    <para>
     optional out parameter for the year
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>monthp</parameter></term>
   <listitem>
    <para>
     optional out parameter for the month
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dayp</parameter></term>
   <listitem>
    <para>
     optional out parameter for the day
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The date field is assumed to be in the form resembling
   [mm[/dd]]/yy[yy] and the result is stored in the out
   parameters any or all of which can be omitted.
   </para><para>

   If the field doesn't exist, all out parameters are set to zero
   and false is returned.  Otherwise, true is returned with any
   invalid part of date set to zero.
   </para><para>

   On return, year, month and day are guaranteed to be in the
   range of [0,9999], [0,12] and [0,31] respectively.
</para>
</refsect1>
</refentry>

<refentry id="API-dmi-walk">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_walk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmi_walk</refname>
 <refpurpose>
     Walk the DMI table and get called back for every record
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dmi_walk </function></funcdef>
   <paramdef>void (*<parameter>decode</parameter>)
     <funcparams>const struct dmi_header *, void *</funcparams></paramdef>
   <paramdef>void * <parameter>private_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>decode</parameter></term>
   <listitem>
    <para>
     Callback function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>private_data</parameter></term>
   <listitem>
    <para>
     Private data to be passed to the callback function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns -1 when the DMI table can't be reached, 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-dmi-match">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_match</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmi_match</refname>
 <refpurpose>
     compare a string to the dmi field (if exists)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>dmi_match </function></funcdef>
   <paramdef>enum dmi_field <parameter>f</parameter></paramdef>
   <paramdef>const char * <parameter>str</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>f</parameter></term>
   <listitem>
    <para>
     DMI field identifier
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>str</parameter></term>
   <listitem>
    <para>
     string to compare the DMI field to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if the requested field equals to the str (including NULL).
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>EDD Interfaces</title>
<!-- drivers/firmware/edd.c -->
<refentry id="API-edd-show-raw-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>edd_show_raw_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>edd_show_raw_data</refname>
 <refpurpose>
  copies raw data to buffer for userspace to parse
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>edd_show_raw_data </function></funcdef>
   <paramdef>struct edd_device * <parameter>edev</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>edev</parameter></term>
   <listitem>
    <para>
     target edd_device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     output buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   number of bytes written, or -EINVAL on failure
</para>
</refsect1>
</refentry>

<refentry id="API-edd-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>edd_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>edd_release</refname>
 <refpurpose>
     free edd structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>edd_release </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>
     kobject of edd structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is called when the refcount of the edd structure
   reaches 0. This should happen right after we unregister,
   but just in case, we use the release callback anyway.
</para>
</refsect1>
</refentry>

<refentry id="API-edd-dev-is-type">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>edd_dev_is_type</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>edd_dev_is_type</refname>
 <refpurpose>
     is this EDD device a 'type' device?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>edd_dev_is_type </function></funcdef>
   <paramdef>struct edd_device * <parameter>edev</parameter></paramdef>
   <paramdef>const char * <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>edev</parameter></term>
   <listitem>
    <para>
     target edd_device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     a host bus or interface identifier string per the EDD spec
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 1 (TRUE) if it is a 'type' device, 0 otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-edd-get-pci-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>edd_get_pci_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>edd_get_pci_dev</refname>
 <refpurpose>
     finds pci_dev that matches edev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_dev * <function>edd_get_pci_dev </function></funcdef>
   <paramdef>struct edd_device * <parameter>edev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>edev</parameter></term>
   <listitem>
    <para>
     edd_device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns pci_dev if found, or NULL
</para>
</refsect1>
</refentry>

<refentry id="API-edd-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>edd_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>edd_init</refname>
 <refpurpose>
     creates sysfs tree of EDD data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>edd_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>
</refentry>

     </sect1>
  </chapter>

  <chapter id="security">
     <title>Security Framework</title>
<!-- security/security.c -->
<refentry id="API-security-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>security_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>security_init</refname>
 <refpurpose>
  initializes the security framework
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>security_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>

   This should be called early in the kernel initialization sequence.
</para>
</refsect1>
</refentry>

<refentry id="API-security-module-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>security_module_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>security_module_enable</refname>
 <refpurpose>
     Load given security module on boot ?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>security_module_enable </function></funcdef>
   <paramdef>struct security_operations * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     a pointer to the struct security_operations that is to be checked.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each LSM must pass this method before registering its own operations
   to avoid security registration races. This method may also be used
   to check if your LSM is currently loaded during kernel initialization.
</para>
</refsect1>
<refsect1>
<title>Return true if</title>
<para>
   -The passed LSM is the one chosen by user at boot time,
   -or the passed LSM is configured as the default and the user did not
   choose an alternate LSM at boot time.
   Otherwise, return false.
</para>
</refsect1>
</refentry>

<refentry id="API-register-security">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_security</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_security</refname>
 <refpurpose>
     registers a security framework with the kernel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_security </function></funcdef>
   <paramdef>struct security_operations * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     a pointer to the struct security_options that is to be registered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function allows a security module to register itself with the
   kernel security subsystem.  Some rudimentary checking is done on the <parameter>ops</parameter>
   value passed to this function. You'll need to check first if your LSM
   is allowed to register its <parameter>ops</parameter> by calling security_module_enable(<parameter>ops</parameter>).
   </para><para>

   If there is already a security module registered with the kernel,
   an error will be returned.  Otherwise <constant>0</constant> is returned on success.
</para>
</refsect1>
</refentry>

<!-- security/inode.c -->
<refentry id="API-securityfs-create-file">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>securityfs_create_file</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>securityfs_create_file</refname>
 <refpurpose>
  create a file in the securityfs filesystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct dentry * <function>securityfs_create_file </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>umode_t <parameter>mode</parameter></paramdef>
   <paramdef>struct dentry * <parameter>parent</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     a pointer to a string containing the name of the file to create.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the permission that the file should have
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     a pointer to the parent dentry for this file.  This should be a
     directory dentry if set.  If this parameter is <constant>NULL</constant>, then the
     file will be created in the root of the securityfs filesystem.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     a pointer to something that the caller will want to get to later
     on.  The inode.i_private pointer will point to this value on
     the <function>open</function> call.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fops</parameter></term>
   <listitem>
    <para>
     a pointer to a struct file_operations that should be used for
     this file.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the basic <quote>create a file</quote> function for securityfs.  It allows for a
   wide range of flexibility in creating a file, or a directory (if you
   want to create a directory, the <function>securityfs_create_dir</function> function is
   recommended to be used instead).
   </para><para>

   This function returns a pointer to a dentry if it succeeds.  This
   pointer must be passed to the <function>securityfs_remove</function> function when the file is
   to be removed (no automatic cleanup happens if your module is unloaded,
   you are responsible here).  If an error occurs, the function will return
   the error value (via ERR_PTR).
   </para><para>

   If securityfs is not enabled in the kernel, the value <constant>-ENODEV</constant> is
   returned.
</para>
</refsect1>
</refentry>

<refentry id="API-securityfs-create-dir">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>securityfs_create_dir</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>securityfs_create_dir</refname>
 <refpurpose>
     create a directory in the securityfs filesystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct dentry * <function>securityfs_create_dir </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct dentry * <parameter>parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     a pointer to a string containing the name of the directory to
     create.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     a pointer to the parent dentry for this file.  This should be a
     directory dentry if set.  If this parameter is <constant>NULL</constant>, then the
     directory will be created in the root of the securityfs filesystem.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function creates a directory in securityfs with the given <parameter>name</parameter>.
   </para><para>

   This function returns a pointer to a dentry if it succeeds.  This
   pointer must be passed to the <function>securityfs_remove</function> function when the file is
   to be removed (no automatic cleanup happens if your module is unloaded,
   you are responsible here).  If an error occurs, <constant>NULL</constant> will be returned.
   </para><para>

   If securityfs is not enabled in the kernel, the value <constant>-ENODEV</constant> is
   returned.  It is not wise to check for this value, but rather, check for
   <constant>NULL</constant> or !<constant>NULL</constant> instead as to eliminate the need for #ifdef in the calling
   code.
</para>
</refsect1>
</refentry>

<refentry id="API-securityfs-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>securityfs_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>securityfs_remove</refname>
 <refpurpose>
     removes a file or directory from the securityfs filesystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>securityfs_remove </function></funcdef>
   <paramdef>struct dentry * <parameter>dentry</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dentry</parameter></term>
   <listitem>
    <para>
     a pointer to a the dentry of the file or directory to be removed.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function removes a file or directory in securityfs that was previously
   created with a call to another securityfs function (like
   <function>securityfs_create_file</function> or variants thereof.)
   </para><para>

   This function is required to be called in order for the file to be
   removed. No automatic cleanup of files will happen when a module is
   removed; you are responsible here.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="audit">
     <title>Audit Interfaces</title>
<!-- kernel/audit.c -->
<refentry id="API-audit-log-start">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_log_start</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_log_start</refname>
 <refpurpose>
  obtain an audit buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct audit_buffer * <function>audit_log_start </function></funcdef>
   <paramdef>struct audit_context * <parameter>ctx</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>int <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     audit_context (may be NULL)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     type of allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     audit message type
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns audit_buffer pointer on success or NULL on error.
   </para><para>

   Obtain an audit buffer.  This routine does locking to obtain the
   audit buffer, but then no locking is required for calls to
   audit_log_*format.  If the task (ctx) is a task that is currently in a
   syscall, then the syscall is marked as auditable and an audit record
   will be written at syscall exit.  If there is no associated task, then
   task context (ctx) should be NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-audit-log-format">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_log_format</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_log_format</refname>
 <refpurpose>
     format a message into the audit buffer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>audit_log_format </function></funcdef>
   <paramdef>struct audit_buffer * <parameter>ab</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ab</parameter></term>
   <listitem>
    <para>
     audit_buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string
     @...: optional parameters matching <parameter>fmt</parameter> string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   All the work is done in audit_log_vformat.
</para>
</refsect1>
</refentry>

<refentry id="API-audit-log-end">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_log_end</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_log_end</refname>
 <refpurpose>
     end one audit record
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>audit_log_end </function></funcdef>
   <paramdef>struct audit_buffer * <parameter>ab</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ab</parameter></term>
   <listitem>
    <para>
     the audit_buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>netlink_unicast</function> cannot be called inside an irq context because it blocks
   (last arg, flags, is not set to MSG_DONTWAIT), so the audit buffer is placed
   on a queue and a tasklet is scheduled to remove them from the queue outside
   the irq context.  May be called in any context.
</para>
</refsect1>
</refentry>

<refentry id="API-audit-log">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_log</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_log</refname>
 <refpurpose>
     Log an audit record
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>audit_log </function></funcdef>
   <paramdef>struct audit_context * <parameter>ctx</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     audit context
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     type of allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     audit message type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string to use
     @...: variable parameters matching the 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 a convenience function that calls audit_log_start,
   audit_log_vformat, and audit_log_end.  It may be called
   in any context.
</para>
</refsect1>
</refentry>

<refentry id="API-audit-log-secctx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_log_secctx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_log_secctx</refname>
 <refpurpose>
     Converts and logs SELinux context
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>audit_log_secctx </function></funcdef>
   <paramdef>struct audit_buffer * <parameter>ab</parameter></paramdef>
   <paramdef>u32 <parameter>secid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ab</parameter></term>
   <listitem>
    <para>
     audit_buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>secid</parameter></term>
   <listitem>
    <para>
     security number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a helper function that calls security_secid_to_secctx to convert
   secid to secctx and then adds the (converted) SELinux context to the audit
   log by calling audit_log_format, thus also preventing leak of internal secid
   to userspace. If secid cannot be converted audit_panic is called.
</para>
</refsect1>
</refentry>

<!-- kernel/auditsc.c -->
<refentry id="API-audit-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_alloc</refname>
 <refpurpose>
  allocate an audit context block for a task
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>audit_alloc </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
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Filter on the task information and allocate a per-task audit context
   if necessary.  Doing so turns on system call auditing for the
   specified task.  This is called from copy_process, so no lock is
   needed.
</para>
</refsect1>
</refentry>

<refentry id="API---audit-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_free</refname>
 <refpurpose>
     free a per-task audit context
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_free </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 whose audit context block to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called from copy_process and do_exit
</para>
</refsect1>
</refentry>

<refentry id="API---audit-syscall-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_syscall_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_syscall_entry</refname>
 <refpurpose>
     fill in an audit record at syscall entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_syscall_entry </function></funcdef>
   <paramdef>int <parameter>major</parameter></paramdef>
   <paramdef>unsigned long <parameter>a1</parameter></paramdef>
   <paramdef>unsigned long <parameter>a2</parameter></paramdef>
   <paramdef>unsigned long <parameter>a3</parameter></paramdef>
   <paramdef>unsigned long <parameter>a4</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>major</parameter></term>
   <listitem>
    <para>
     major syscall type (function)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>a1</parameter></term>
   <listitem>
    <para>
     additional syscall register 1
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>a2</parameter></term>
   <listitem>
    <para>
     additional syscall register 2
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>a3</parameter></term>
   <listitem>
    <para>
     additional syscall register 3
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>a4</parameter></term>
   <listitem>
    <para>
     additional syscall register 4
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Fill in audit context at syscall entry.  This only happens if the
   audit context was created when the task was created and the state or
   filters demand the audit context be built.  If the state from the
   per-task filter or from the per-syscall filter is AUDIT_RECORD_CONTEXT,
   then the record will be written at syscall exit time (otherwise, it
   will only be written if another part of the kernel requests that it
   be written).
</para>
</refsect1>
</refentry>

<refentry id="API---audit-syscall-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_syscall_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_syscall_exit</refname>
 <refpurpose>
     deallocate audit context after a system call
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_syscall_exit </function></funcdef>
   <paramdef>int <parameter>success</parameter></paramdef>
   <paramdef>long <parameter>return_code</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>success</parameter></term>
   <listitem>
    <para>
     success value of the syscall
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>return_code</parameter></term>
   <listitem>
    <para>
     return value of the syscall
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Tear down after system call.  If the audit context has been marked as
   auditable (either because of the AUDIT_RECORD_CONTEXT state from
   filtering, or because some other part of the kernel wrote an audit
   message), then write out the syscall information.  In call cases,
   free the names stored from <function>getname</function>.
</para>
</refsect1>
</refentry>

<refentry id="API---audit-reusename">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_reusename</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_reusename</refname>
 <refpurpose>
     fill out filename with info from existing entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct filename * <function>__audit_reusename </function></funcdef>
   <paramdef>const __user char * <parameter>uptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>uptr</parameter></term>
   <listitem>
    <para>
     userland ptr to pathname
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Search the audit_names list for the current audit context. If there is an
   existing entry with a matching <quote>uptr</quote> then return the filename
   associated with that audit_name. If not, return NULL.
</para>
</refsect1>
</refentry>

<refentry id="API---audit-getname">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_getname</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_getname</refname>
 <refpurpose>
     add a name to the list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_getname </function></funcdef>
   <paramdef>struct filename * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add a name to the list of audit names for this context.
   Called from fs/namei.c:<function>getname</function>.
</para>
</refsect1>
</refentry>

<refentry id="API---audit-inode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_inode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_inode</refname>
 <refpurpose>
     store the inode and device from a lookup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_inode </function></funcdef>
   <paramdef>struct filename * <parameter>name</parameter></paramdef>
   <paramdef>const struct dentry * <parameter>dentry</parameter></paramdef>
   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name being audited
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dentry</parameter></term>
   <listitem>
    <para>
     dentry being audited
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     attributes for this particular entry
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-auditsc-get-stamp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>auditsc_get_stamp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>auditsc_get_stamp</refname>
 <refpurpose>
     get local copies of audit_context values
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>auditsc_get_stamp </function></funcdef>
   <paramdef>struct audit_context * <parameter>ctx</parameter></paramdef>
   <paramdef>struct timespec * <parameter>t</parameter></paramdef>
   <paramdef>unsigned int * <parameter>serial</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     audit_context for the task
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>t</parameter></term>
   <listitem>
    <para>
     timespec to store time recorded in the audit_context
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>serial</parameter></term>
   <listitem>
    <para>
     serial value that is recorded in the audit_context
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Also sets the context as auditable.
</para>
</refsect1>
</refentry>

<refentry id="API-audit-set-loginuid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_set_loginuid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_set_loginuid</refname>
 <refpurpose>
     set current task's audit_context loginuid
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>audit_set_loginuid </function></funcdef>
   <paramdef>kuid_t <parameter>loginuid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>loginuid</parameter></term>
   <listitem>
    <para>
     loginuid value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0.
   </para><para>

   Called (set) from fs/proc/base.c::<function>proc_loginuid_write</function>.
</para>
</refsect1>
</refentry>

<refentry id="API---audit-mq-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_mq_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_mq_open</refname>
 <refpurpose>
     record audit data for a POSIX MQ open
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_mq_open </function></funcdef>
   <paramdef>int <parameter>oflag</parameter></paramdef>
   <paramdef>umode_t <parameter>mode</parameter></paramdef>
   <paramdef>struct mq_attr * <parameter>attr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>oflag</parameter></term>
   <listitem>
    <para>
     open flag
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     queue attributes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---audit-mq-sendrecv">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_mq_sendrecv</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_mq_sendrecv</refname>
 <refpurpose>
     record audit data for a POSIX MQ timed send/receive
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_mq_sendrecv </function></funcdef>
   <paramdef>mqd_t <parameter>mqdes</parameter></paramdef>
   <paramdef>size_t <parameter>msg_len</parameter></paramdef>
   <paramdef>unsigned int <parameter>msg_prio</parameter></paramdef>
   <paramdef>const struct timespec * <parameter>abs_timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mqdes</parameter></term>
   <listitem>
    <para>
     MQ descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg_len</parameter></term>
   <listitem>
    <para>
     Message length
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg_prio</parameter></term>
   <listitem>
    <para>
     Message priority
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>abs_timeout</parameter></term>
   <listitem>
    <para>
     Message timeout in absolute time
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---audit-mq-notify">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_mq_notify</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_mq_notify</refname>
 <refpurpose>
     record audit data for a POSIX MQ notify
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_mq_notify </function></funcdef>
   <paramdef>mqd_t <parameter>mqdes</parameter></paramdef>
   <paramdef>const struct sigevent * <parameter>notification</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mqdes</parameter></term>
   <listitem>
    <para>
     MQ descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>notification</parameter></term>
   <listitem>
    <para>
     Notification event
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---audit-mq-getsetattr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_mq_getsetattr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_mq_getsetattr</refname>
 <refpurpose>
     record audit data for a POSIX MQ get/set attribute
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_mq_getsetattr </function></funcdef>
   <paramdef>mqd_t <parameter>mqdes</parameter></paramdef>
   <paramdef>struct mq_attr * <parameter>mqstat</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mqdes</parameter></term>
   <listitem>
    <para>
     MQ descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mqstat</parameter></term>
   <listitem>
    <para>
     MQ flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---audit-ipc-obj">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_ipc_obj</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_ipc_obj</refname>
 <refpurpose>
     record audit data for ipc object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_ipc_obj </function></funcdef>
   <paramdef>struct kern_ipc_perm * <parameter>ipcp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ipcp</parameter></term>
   <listitem>
    <para>
     ipc permissions
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---audit-ipc-set-perm">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_ipc_set_perm</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_ipc_set_perm</refname>
 <refpurpose>
     record audit data for new ipc permissions
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_ipc_set_perm </function></funcdef>
   <paramdef>unsigned long <parameter>qbytes</parameter></paramdef>
   <paramdef>uid_t <parameter>uid</parameter></paramdef>
   <paramdef>gid_t <parameter>gid</parameter></paramdef>
   <paramdef>umode_t <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>qbytes</parameter></term>
   <listitem>
    <para>
     msgq bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uid</parameter></term>
   <listitem>
    <para>
     msgq user id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gid</parameter></term>
   <listitem>
    <para>
     msgq group id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     msgq mode (permissions)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called only after <function>audit_ipc_obj</function>.
</para>
</refsect1>
</refentry>

<refentry id="API---audit-socketcall">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_socketcall</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_socketcall</refname>
 <refpurpose>
     record audit data for sys_socketcall
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__audit_socketcall </function></funcdef>
   <paramdef>int <parameter>nargs</parameter></paramdef>
   <paramdef>unsigned long * <parameter>args</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nargs</parameter></term>
   <listitem>
    <para>
     number of args, which should not be more than AUDITSC_ARGS.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args</parameter></term>
   <listitem>
    <para>
     args array
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---audit-fd-pair">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_fd_pair</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_fd_pair</refname>
 <refpurpose>
     record audit data for pipe and socketpair
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_fd_pair </function></funcdef>
   <paramdef>int <parameter>fd1</parameter></paramdef>
   <paramdef>int <parameter>fd2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fd1</parameter></term>
   <listitem>
    <para>
     the first file descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fd2</parameter></term>
   <listitem>
    <para>
     the second file descriptor
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---audit-sockaddr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_sockaddr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_sockaddr</refname>
 <refpurpose>
     record audit data for sys_bind, sys_connect, sys_sendto
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__audit_sockaddr </function></funcdef>
   <paramdef>int <parameter>len</parameter></paramdef>
   <paramdef>void * <parameter>a</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     data length in user space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>a</parameter></term>
   <listitem>
    <para>
     data address in kernel space
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success or NULL context or &lt; 0 on error.
</para>
</refsect1>
</refentry>

<refentry id="API---audit-signal-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_signal_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_signal_info</refname>
 <refpurpose>
     record signal info for shutting down audit subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__audit_signal_info </function></funcdef>
   <paramdef>int <parameter>sig</parameter></paramdef>
   <paramdef>struct task_struct * <parameter>t</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sig</parameter></term>
   <listitem>
    <para>
     signal value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>t</parameter></term>
   <listitem>
    <para>
     task being signaled
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the audit subsystem is being terminated, record the task (pid)
   and uid that is doing that.
</para>
</refsect1>
</refentry>

<refentry id="API---audit-log-bprm-fcaps">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_log_bprm_fcaps</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_log_bprm_fcaps</refname>
 <refpurpose>
     store information about a loading bprm and relevant fcaps
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__audit_log_bprm_fcaps </function></funcdef>
   <paramdef>struct linux_binprm * <parameter>bprm</parameter></paramdef>
   <paramdef>const struct cred * <parameter>new</parameter></paramdef>
   <paramdef>const struct cred * <parameter>old</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bprm</parameter></term>
   <listitem>
    <para>
     pointer to the bprm being processed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     the proposed new credentials
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     the old credentials
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Simply check if the proc already has the caps given by the file and if not
   store the priv escalation info for later auditing at the end of the syscall
   </para><para>

   -Eric
</para>
</refsect1>
</refentry>

<refentry id="API---audit-log-capset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_log_capset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_log_capset</refname>
 <refpurpose>
     store information about the arguments to the capset syscall
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_log_capset </function></funcdef>
   <paramdef>const struct cred * <parameter>new</parameter></paramdef>
   <paramdef>const struct cred * <parameter>old</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     the new credentials
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     the old (current) credentials
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Record the arguments userspace sent to sys_capset for later printing by the
   audit system if applicable
</para>
</refsect1>
</refentry>

<refentry id="API-audit-core-dumps">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_core_dumps</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_core_dumps</refname>
 <refpurpose>
     record information about processes that end abnormally
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>audit_core_dumps </function></funcdef>
   <paramdef>long <parameter>signr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>signr</parameter></term>
   <listitem>
    <para>
     signal value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a process ends with a core dump, something fishy is going on and we
   should record the event for investigation.
</para>
</refsect1>
</refentry>

<!-- kernel/auditfilter.c -->
<refentry id="API-audit-rule-change">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_rule_change</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_rule_change</refname>
 <refpurpose>
  apply all rules to the specified message type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>audit_rule_change </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>__u32 <parameter>portid</parameter></paramdef>
   <paramdef>int <parameter>seq</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>datasz</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     audit message type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>portid</parameter></term>
   <listitem>
    <para>
     target port id for netlink audit messages
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>seq</parameter></term>
   <listitem>
    <para>
     netlink audit message sequence (serial) number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     payload data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>datasz</parameter></term>
   <listitem>
    <para>
     size of payload data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-audit-list-rules-send">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_list_rules_send</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_list_rules_send</refname>
 <refpurpose>
     list the audit rules
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>audit_list_rules_send </function></funcdef>
   <paramdef>struct sk_buff * <parameter>request_skb</parameter></paramdef>
   <paramdef>int <parameter>seq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>request_skb</parameter></term>
   <listitem>
    <para>
     skb of request we are replying to (used to target the reply)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>seq</parameter></term>
   <listitem>
    <para>
     netlink audit message sequence (serial) number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-parent-len">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parent_len</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parent_len</refname>
 <refpurpose>
     find the length of the parent portion of a pathname
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parent_len </function></funcdef>
   <paramdef>const char * <parameter>path</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>path</parameter></term>
   <listitem>
    <para>
     pathname of which to determine length
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-audit-compare-dname-path">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_compare_dname_path</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_compare_dname_path</refname>
 <refpurpose>
     compare given dentry name with last component in given path. Return of 0 indicates a match.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>audit_compare_dname_path </function></funcdef>
   <paramdef>const char * <parameter>dname</parameter></paramdef>
   <paramdef>const char * <parameter>path</parameter></paramdef>
   <paramdef>int <parameter>parentlen</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dname</parameter></term>
   <listitem>
    <para>
     dentry name that we're comparing
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>path</parameter></term>
   <listitem>
    <para>
     full pathname that we're comparing
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parentlen</parameter></term>
   <listitem>
    <para>
     length of the parent if known. Passing in AUDIT_NAME_FULL
     here indicates that we must compute this value.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

  </chapter>

  <chapter id="accounting">
     <title>Accounting Framework</title>
<!-- kernel/acct.c -->
<refentry id="API-sys-acct">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_acct</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sys_acct</refname>
 <refpurpose>
  enable/disable process accounting
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>sys_acct </function></funcdef>
   <paramdef>const char __user * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     file name for accounting records or NULL to shutdown accounting
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success or negative errno values for failure.
   </para><para>

   <function>sys_acct</function> is the only system call needed to implement process
   accounting. It takes the name of the file where accounting records
   should be written. If the filename is NULL, accounting will be
   shutdown.
</para>
</refsect1>
</refentry>

<refentry id="API-acct-collect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acct_collect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acct_collect</refname>
 <refpurpose>
     collect accounting information into pacct_struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>acct_collect </function></funcdef>
   <paramdef>long <parameter>exitcode</parameter></paramdef>
   <paramdef>int <parameter>group_dead</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>exitcode</parameter></term>
   <listitem>
    <para>
     task exit code
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>group_dead</parameter></term>
   <listitem>
    <para>
     not 0, if this thread is the last one in the process.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-acct-process">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acct_process</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acct_process</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>acct_process </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>

   handles process accounting for an exiting task
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="blkdev">
     <title>Block Devices</title>
<!-- block/blk-core.c -->
<refentry id="API-blk-get-backing-dev-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_get_backing_dev_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_get_backing_dev_info</refname>
 <refpurpose>
  get the address of a queue's backing_dev_info
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct backing_dev_info * <function>blk_get_backing_dev_info </function></funcdef>
   <paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bdev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Locates the passed device's request queue and returns the address of its
   backing_dev_info.  This function can only be called if <parameter>bdev</parameter> is opened
   and the return value is never NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-delay-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_delay_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_delay_queue</refname>
 <refpurpose>
     restart queueing after defined interval
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_delay_queue </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned long <parameter>msecs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     The <structname>struct request_queue</structname> in question
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msecs</parameter></term>
   <listitem>
    <para>
     Delay in msecs
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sometimes queueing needs to be postponed for a little while, to allow
   resources to come back. This function will make sure that queueing is
   restarted around the specified time. Queue lock must be held.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-start-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_start_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_start_queue</refname>
 <refpurpose>
     restart a previously stopped queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_start_queue </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     The <structname>struct request_queue</structname> in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>blk_start_queue</function> will clear the stop flag on the queue, and call
   the request_fn for the queue if it was in a stopped state when
   entered. Also see <function>blk_stop_queue</function>. Queue lock must be held.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-stop-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_stop_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_stop_queue</refname>
 <refpurpose>
     stop a queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_stop_queue </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     The <structname>struct request_queue</structname> in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The Linux block layer assumes that a block driver will consume all
   entries on the request queue when the request_fn strategy is called.
   Often this will not happen, because of hardware limitations (queue
   depth settings). If a device driver gets a 'queue full' response,
   or if it simply chooses not to queue more I/O at one point, it can
   call this function to prevent the request_fn from being called until
   the driver has signalled it's ready to go again. This happens by calling
   <function>blk_start_queue</function> to restart queue operations. Queue lock must be held.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-sync-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_sync_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_sync_queue</refname>
 <refpurpose>
     cancel any pending callbacks on a queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_sync_queue </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The block layer may perform asynchronous callback activity
   on a queue, such as calling the unplug function after a timeout.
   A block device may call blk_sync_queue to ensure that any
   such activity is cancelled, thus allowing it to release resources
   that the callbacks might use. The caller must already have made sure
   that its -&gt;make_request_fn will not re-add plugging prior to calling
   this function.
   </para><para>

   This function does not cancel any asynchronous activity arising
   out of elevator or throttling code. That would require <function>elevator_exit</function>
   and <function>blkcg_exit_queue</function> to be called with queue lock initialized.
</para>
</refsect1>
</refentry>

<refentry id="API---blk-run-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__blk_run_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__blk_run_queue</refname>
 <refpurpose>
     run a single device queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__blk_run_queue </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     The queue to run
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   See <parameter>blk_run_queue</parameter>. This variant must be called with the queue lock
   held and interrupts disabled.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-run-queue-async">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_run_queue_async</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_run_queue_async</refname>
 <refpurpose>
     run a single device queue in workqueue context
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_run_queue_async </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     The queue to run
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Tells kblockd to perform the equivalent of <parameter>blk_run_queue</parameter> on behalf
   of us. The caller must hold the queue lock.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-run-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_run_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_run_queue</refname>
 <refpurpose>
     run a single device queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_run_queue </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     The queue to run
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Invoke request handling on this queue, if it has pending work to do.
   May be used to restart queueing when a request has completed.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-bypass-start">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_bypass_start</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_bypass_start</refname>
 <refpurpose>
     enter queue bypass mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_bypass_start </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue of interest
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   In bypass mode, only the dispatch FIFO queue of <parameter>q</parameter> is used.  This
   function makes <parameter>q</parameter> enter bypass mode and drains all requests which were
   throttled or issued before.  On return, it's guaranteed that no request
   is being throttled or has ELVPRIV set and <function>blk_queue_bypass</function> <constant>true</constant>
   inside queue or RCU read lock.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-bypass-end">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_bypass_end</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_bypass_end</refname>
 <refpurpose>
     leave queue bypass mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_bypass_end </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue of interest
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Leave bypass mode and restore the normal queueing behavior.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-cleanup-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_cleanup_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_cleanup_queue</refname>
 <refpurpose>
     shutdown a request queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_cleanup_queue </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     request queue to shutdown
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Mark <parameter>q</parameter> DYING, drain all pending requests, mark <parameter>q</parameter> DEAD, destroy and
   put it.  All future requests will be failed immediately with -ENODEV.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-init-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_init_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_init_queue</refname>
 <refpurpose>
     prepare a request queue for use with a block device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct request_queue * <function>blk_init_queue </function></funcdef>
   <paramdef>request_fn_proc * <parameter>rfn</parameter></paramdef>
   <paramdef>spinlock_t * <parameter>lock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rfn</parameter></term>
   <listitem>
    <para>
     The function to be called to process requests that have been
     placed on the queue.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     Request queue spin lock
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a block device wishes to use the standard request handling procedures,
   which sorts requests and coalesces adjacent requests, then it must
   call <function>blk_init_queue</function>.  The function <parameter>rfn</parameter> will be called when there
   are requests on the queue that need to be processed.  If the device
   supports plugging, then <parameter>rfn</parameter> may not be called immediately when requests
   are available on the queue, but may be called at some time later instead.
   Plugged queues are generally unplugged when a buffer belonging to one
   of the requests on the queue is needed, or due to memory pressure.
   </para><para>

   <parameter>rfn</parameter> is not required, or even expected, to remove all requests off the
   queue, but only as many as it can handle at a time.  If it does leave
   requests on the queue, it is responsible for arranging that the requests
   get dealt with eventually.
   </para><para>

   The queue spin lock must be held while manipulating the requests on the
   request queue; this lock will be taken also from interrupt context, so irq
   disabling is needed for it.
   </para><para>

   Function returns a pointer to the initialized request queue, or <constant>NULL</constant> if
   it didn't succeed.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   <function>blk_init_queue</function> must be paired with a <function>blk_cleanup_queue</function> call
   when the block device is deactivated (such as at module unload).
</para>
</refsect1>
</refentry>

<refentry id="API-blk-make-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_make_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_make_request</refname>
 <refpurpose>
     given a bio, allocate a corresponding struct request.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct request * <function>blk_make_request </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     target request queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     The bio describing the memory mappings that will be submitted for IO.
     It may be a chained-bio properly constructed by block/bio layer.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     gfp flags to be used for memory allocation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   blk_make_request is the parallel of generic_make_request for BLOCK_PC
   type commands. Where the struct request needs to be farther initialized by
   the caller. It is passed a <structname>struct bio</structname>, which describes the memory info of
   the I/O transfer.
   </para><para>

   The caller of blk_make_request must make sure that bi_io_vec
   are set to describe the memory buffers. That <function>bio_data_dir</function> will return
   the needed direction of the request. (And all bio's in the passed bio-chain
   are properly set accordingly)
   </para><para>

   If called under none-sleepable conditions, mapped bio buffers must not
   need bouncing, by calling the appropriate masked or flagged allocator,
   suitable for the target device. Otherwise the call to blk_queue_bounce will
   BUG.
</para>
</refsect1>
<refsect1>
<title>WARNING</title>
<para>
   When allocating/cloning a bio-chain, careful consideration should be
   given to how you allocate bios. In particular, you cannot use __GFP_WAIT for
   anything but the first bio in the chain. Otherwise you risk waiting for IO
   completion of a bio that hasn't been submitted yet, thus resulting in a
   deadlock. Alternatively bios should be allocated using <function>bio_kmalloc</function> instead
   of <function>bio_alloc</function>, as that avoids the mempool deadlock.
   If possible a big IO should be split into smaller parts when allocation
   fails. Partial allocation should not be an error, or you risk a live-lock.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-rq-set-block-pc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_set_block_pc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_set_block_pc</refname>
 <refpurpose>
     initialize a request to type BLOCK_PC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_rq_set_block_pc </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     request to be initialized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-blk-requeue-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_requeue_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_requeue_request</refname>
 <refpurpose>
     put a request back on queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_requeue_request </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     request queue where request should be inserted
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     request to be inserted
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers often keep queueing requests until the hardware cannot accept
   more, when that condition happens we need to put the request back
   on the queue. Must be called with queue lock held.
</para>
</refsect1>
</refentry>

<refentry id="API-part-round-stats">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>part_round_stats</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>part_round_stats</refname>
 <refpurpose>
     Round off the performance stats on a struct disk_stats.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>part_round_stats </function></funcdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
   <paramdef>struct hd_struct * <parameter>part</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     cpu number for stats access
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>part</parameter></term>
   <listitem>
    <para>
     target partition
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The average IO queue length and utilisation statistics are maintained
   by observing the current state of the queue length and the amount of
   time it has been in this state for.
   </para><para>

   Normally, that accounting is done on IO completion, but that can result
   in more than a second's worth of IO being accounted for within any one
   second, leading to &gt;100% utilisation.  To deal with that, we call this
   function to do a round-off before returning the results when reading
   /proc/diskstats.  This accounts immediately for all queue usage up to
   the current jiffies and restarts the counters again.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-add-request-payload">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_add_request_payload</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_add_request_payload</refname>
 <refpurpose>
     add a payload to a request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_add_request_payload </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     request to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     page backing the payload
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of the payload.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This allows to later add a payload to an already submitted request by
   a block driver.  The driver needs to take care of freeing the payload
   itself.
   </para><para>

   Note that this is a quite horrible hack and nothing but handling of
   discard requests should ever use it.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-make-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_make_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_make_request</refname>
 <refpurpose>
     hand a buffer to its device driver for I/O
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>generic_make_request </function></funcdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     The bio describing the location in memory and on the device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>generic_make_request</function> is used to make I/O requests of block
   devices. It is passed a <structname>struct bio</structname>, which describes the I/O that needs
   to be done.
   </para><para>

   <function>generic_make_request</function> does not return any status.  The
   success/failure status of the request, along with notification of
   completion, is delivered asynchronously through the bio-&gt;bi_end_io
   function described (one day) else where.
   </para><para>

   The caller of generic_make_request must make sure that bi_io_vec
   are set to describe the memory buffer, and that bi_dev and bi_sector are
   set to describe the device address, and the
   bi_end_io and optionally bi_private are set to describe how
   completion notification should be signaled.
   </para><para>

   generic_make_request and the drivers it calls may use bi_next if this
   bio happens to be merged with someone else, and may resubmit the bio to
   a lower device by calling into generic_make_request recursively, which
   means the bio should NOT be touched after the call to -&gt;make_request_fn.
</para>
</refsect1>
</refentry>

<refentry id="API-submit-bio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>submit_bio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>submit_bio</refname>
 <refpurpose>
     submit a bio to the block device layer for I/O
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>submit_bio </function></funcdef>
   <paramdef>int <parameter>rw</parameter></paramdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rw</parameter></term>
   <listitem>
    <para>
     whether to <constant>READ</constant> or <constant>WRITE</constant>, or maybe to <constant>READA</constant> (read ahead)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     The <structname>struct bio</structname> which describes the I/O
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>submit_bio</function> is very similar in purpose to <function>generic_make_request</function>, and
   uses that function to do most of the work. Both are fairly rough
   interfaces; <parameter>bio</parameter> must be presetup and ready for I/O.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-rq-check-limits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_check_limits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_check_limits</refname>
 <refpurpose>
     Helper function to check a request for the queue limit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_rq_check_limits </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request being checked
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <parameter>rq</parameter> may have been made based on weaker limitations of upper-level queues
   in request stacking drivers, and it may violate the limitation of <parameter>q</parameter>.
   Since the block layer and the underlying device driver trust <parameter>rq</parameter>
   after it is inserted to <parameter>q</parameter>, it should be checked against <parameter>q</parameter> before
   the insertion using this generic function.
   </para><para>

   This function should also be useful for request stacking drivers
   in some cases below, so export this function.
   Request stacking drivers like request-based dm may change the queue
   limits while requests are in the queue (e.g. dm's table swapping).
   Such request stacking drivers should check those requests against
   the new queue limits again when they dispatch those requests,
   although such checkings are also done against the old queue limits
   when submitting requests.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-insert-cloned-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_insert_cloned_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_insert_cloned_request</refname>
 <refpurpose>
     Helper for stacking drivers to submit a request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_insert_cloned_request </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the queue to submit the request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request being queued
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-blk-rq-err-bytes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_err_bytes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_err_bytes</refname>
 <refpurpose>
     determine number of bytes till the next failure boundary
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>blk_rq_err_bytes </function></funcdef>
   <paramdef>const struct request * <parameter>rq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     request to examine
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A request could be merge of IOs which require different failure
   handling.  This function determines the number of bytes which
   can be failed from the beginning of the request without
   crossing into area which need to be retried further.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The number of bytes to fail.
</para>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   queue_lock must be held.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-peek-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_peek_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_peek_request</refname>
 <refpurpose>
     peek at the top of a request queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct request * <function>blk_peek_request </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     request queue to peek at
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return the request at the top of <parameter>q</parameter>.  The returned request
   should be started using <function>blk_start_request</function> before LLD starts
   processing it.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Pointer to the request at the top of <parameter>q</parameter> if available.  Null
   otherwise.
</para>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   queue_lock must be held.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-start-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_start_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_start_request</refname>
 <refpurpose>
     start request processing on the driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_start_request </function></funcdef>
   <paramdef>struct request * <parameter>req</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     request to dequeue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Dequeue <parameter>req</parameter> and start timeout timer on it.  This hands off the
   request to the driver.
   </para><para>

   Block internal functions which don't want to start timer should
   call <function>blk_dequeue_request</function>.
</para>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   queue_lock must be held.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-fetch-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_fetch_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_fetch_request</refname>
 <refpurpose>
     fetch a request from a request queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct request * <function>blk_fetch_request </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     request queue to fetch a request from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return the request at the top of <parameter>q</parameter>.  The request is started on
   return and LLD can start processing it immediately.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Pointer to the request at the top of <parameter>q</parameter> if available.  Null
   otherwise.
</para>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   queue_lock must be held.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-update-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_update_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_update_request</refname>
 <refpurpose>
     Special helper function for request stacking drivers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>blk_update_request </function></funcdef>
   <paramdef>struct request * <parameter>req</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
   <paramdef>unsigned int <parameter>nr_bytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     the request being processed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     <constant>0</constant> for success, &lt; <constant>0</constant> for error
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_bytes</parameter></term>
   <listitem>
    <para>
     number of bytes to complete <parameter>req</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Ends I/O on a number of bytes attached to <parameter>req</parameter>, but doesn't complete
   the request structure even if <parameter>req</parameter> doesn't have leftover.
   If <parameter>req</parameter> has leftover, sets it up for the next range of segments.
   </para><para>

   This special helper function is only for request stacking drivers
   (e.g. request-based dm) so that they can handle partial completion.
   Actual device drivers should use blk_end_request instead.
   </para><para>

   Passing the result of <function>blk_rq_bytes</function> as <parameter>nr_bytes</parameter> guarantees
   <constant>false</constant> return from this function.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> - this request doesn't have any more data
   <constant>true</constant>  - this request has more data
</para>
</refsect1>
</refentry>

<refentry id="API-blk-unprep-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_unprep_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_unprep_request</refname>
 <refpurpose>
     unprepare a request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_unprep_request </function></funcdef>
   <paramdef>struct request * <parameter>req</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     the request
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function makes a request ready for complete resubmission (or
   completion).  It happens only after all error handling is complete,
   so represents the appropriate moment to deallocate any resources
   that were allocated to the request in the prep_rq_fn.  The queue
   lock is held when calling this.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-end-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_end_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_end_request</refname>
 <refpurpose>
     Helper function for drivers to complete the request.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>blk_end_request </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
   <paramdef>unsigned int <parameter>nr_bytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request being processed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     <constant>0</constant> for success, &lt; <constant>0</constant> for error
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_bytes</parameter></term>
   <listitem>
    <para>
     number of bytes to complete
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Ends I/O on a number of bytes attached to <parameter>rq</parameter>.
   If <parameter>rq</parameter> has leftover, sets it up for the next range of segments.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> - we are done with this request
   <constant>true</constant>  - still buffers pending for this request
</para>
</refsect1>
</refentry>

<refentry id="API-blk-end-request-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_end_request_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_end_request_all</refname>
 <refpurpose>
     Helper function for drives to finish the request.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_end_request_all </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request to finish
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     <constant>0</constant> for success, &lt; <constant>0</constant> for error
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Completely finish <parameter>rq</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-end-request-cur">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_end_request_cur</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_end_request_cur</refname>
 <refpurpose>
     Helper function to finish the current request chunk.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>blk_end_request_cur </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request to finish the current chunk for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     <constant>0</constant> for success, &lt; <constant>0</constant> for error
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Complete the current consecutively mapped chunk from <parameter>rq</parameter>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> - we are done with this request
   <constant>true</constant>  - still buffers pending for this request
</para>
</refsect1>
</refentry>

<refentry id="API-blk-end-request-err">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_end_request_err</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_end_request_err</refname>
 <refpurpose>
     Finish a request till the next failure boundary.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>blk_end_request_err </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request to finish till the next failure boundary for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     must be negative errno
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Complete <parameter>rq</parameter> till the next failure boundary.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> - we are done with this request
   <constant>true</constant>  - still buffers pending for this request
</para>
</refsect1>
</refentry>

<refentry id="API---blk-end-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__blk_end_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__blk_end_request</refname>
 <refpurpose>
     Helper function for drivers to complete the request.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>__blk_end_request </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
   <paramdef>unsigned int <parameter>nr_bytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request being processed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     <constant>0</constant> for success, &lt; <constant>0</constant> for error
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_bytes</parameter></term>
   <listitem>
    <para>
     number of bytes to complete
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Must be called with queue lock held unlike <function>blk_end_request</function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> - we are done with this request
   <constant>true</constant>  - still buffers pending for this request
</para>
</refsect1>
</refentry>

<refentry id="API---blk-end-request-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__blk_end_request_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__blk_end_request_all</refname>
 <refpurpose>
     Helper function for drives to finish the request.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__blk_end_request_all </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request to finish
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     <constant>0</constant> for success, &lt; <constant>0</constant> for error
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Completely finish <parameter>rq</parameter>.  Must be called with queue lock held.
</para>
</refsect1>
</refentry>

<refentry id="API---blk-end-request-cur">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__blk_end_request_cur</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__blk_end_request_cur</refname>
 <refpurpose>
     Helper function to finish the current request chunk.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>__blk_end_request_cur </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request to finish the current chunk for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     <constant>0</constant> for success, &lt; <constant>0</constant> for error
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Complete the current consecutively mapped chunk from <parameter>rq</parameter>.  Must
   be called with queue lock held.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> - we are done with this request
   <constant>true</constant>  - still buffers pending for this request
</para>
</refsect1>
</refentry>

<refentry id="API---blk-end-request-err">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__blk_end_request_err</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__blk_end_request_err</refname>
 <refpurpose>
     Finish a request till the next failure boundary.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>__blk_end_request_err </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request to finish till the next failure boundary for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     must be negative errno
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Complete <parameter>rq</parameter> till the next failure boundary.  Must be called
   with queue lock held.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> - we are done with this request
   <constant>true</constant>  - still buffers pending for this request
</para>
</refsect1>
</refentry>

<refentry id="API-rq-flush-dcache-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rq_flush_dcache_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rq_flush_dcache_pages</refname>
 <refpurpose>
     Helper function to flush all pages in a request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>rq_flush_dcache_pages </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request to be flushed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Flush all pages in <parameter>rq</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-lld-busy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_lld_busy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_lld_busy</refname>
 <refpurpose>
     Check if underlying low-level drivers of a device are busy
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_lld_busy </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the queue of the device being checked
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check if underlying low-level drivers of a device are busy.
   If the drivers want to export their busy state, they must set own
   exporting function using <function>blk_queue_lld_busy</function> first.
   </para><para>

   Basically, this function is used only by request stacking drivers
   to stop dispatching requests to underlying devices when underlying
   devices are busy.  This behavior helps more I/O merging on the queue
   of the request stacking driver and prevents I/O throughput regression
   on burst I/O load.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 - Not busy (The request stacking driver should dispatch request)
   1 - Busy (The request stacking driver should stop dispatching request)
</para>
</refsect1>
</refentry>

<refentry id="API-blk-rq-unprep-clone">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_unprep_clone</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_unprep_clone</refname>
 <refpurpose>
     Helper function to free all bios in a cloned request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_rq_unprep_clone </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the clone request to be cleaned up
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free all bios in <parameter>rq</parameter> for a cloned request.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-rq-prep-clone">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_prep_clone</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_prep_clone</refname>
 <refpurpose>
     Helper function to setup clone request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_rq_prep_clone </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>struct request * <parameter>rq_src</parameter></paramdef>
   <paramdef>struct bio_set * <parameter>bs</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>int (*<parameter>bio_ctr</parameter>)
     <funcparams>struct bio *, struct bio *, void *</funcparams></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request to be setup
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq_src</parameter></term>
   <listitem>
    <para>
     original request to be cloned
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bs</parameter></term>
   <listitem>
    <para>
     bio_set that bios for clone are allocated from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation mask for bio
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bio_ctr</parameter></term>
   <listitem>
    <para>
     setup function to be called for each clone bio.
     Returns <constant>0</constant> for success, non <constant>0</constant> for failure.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     private data to be passed to <parameter>bio_ctr</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Clones bios in <parameter>rq_src</parameter> to <parameter>rq</parameter>, and copies attributes of <parameter>rq_src</parameter> to <parameter>rq</parameter>.
   The actual data parts of <parameter>rq_src</parameter> (e.g. -&gt;cmd, -&gt;sense)
   are not copied, and copying such parts is the caller's responsibility.
   Also, pages which the original bios are pointing to are not copied
   and the cloned bios just point same pages.
   So cloned bios must be completed before original bios, which means
   the caller must complete <parameter>rq</parameter> before <parameter>rq_src</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-start-plug">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_start_plug</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_start_plug</refname>
 <refpurpose>
     initialize blk_plug and track it inside the task_struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_start_plug </function></funcdef>
   <paramdef>struct blk_plug * <parameter>plug</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plug</parameter></term>
   <listitem>
    <para>
     The <structname>struct blk_plug</structname> that needs to be initialized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Tracking blk_plug inside the task_struct will help with auto-flushing the
   pending I/O should the task end up blocking between <function>blk_start_plug</function> and
   <function>blk_finish_plug</function>. This is important from a performance perspective, but
   also ensures that we don't deadlock. For instance, if the task is blocking
   for a memory allocation, memory reclaim could end up wanting to free a
   page belonging to that request that is currently residing in our private
   plug. By flushing the pending I/O when the process goes to sleep, we avoid
   this kind of deadlock.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-pm-runtime-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_pm_runtime_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_pm_runtime_init</refname>
 <refpurpose>
     Block layer runtime PM initialization routine
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_pm_runtime_init </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the queue of the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the device the queue belongs to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize runtime-PM-related fields for <parameter>q</parameter> and start auto suspend for
   <parameter>dev</parameter>. Drivers that want to take advantage of request-based runtime PM
   should call this function after <parameter>dev</parameter> has been initialized, and its
   request queue <parameter>q</parameter> has been allocated, and runtime PM for it can not happen
   yet(either due to disabled/forbidden or its usage_count &gt; 0). In most
   cases, driver should call this function before any I/O has taken place.
   </para><para>

   This function takes care of setting up using auto suspend for the device,
   the autosuspend delay is set to -1 to make runtime suspend impossible
   until an updated value is either set by user or by driver. Drivers do
   not need to touch other autosuspend settings.
   </para><para>

   The block layer runtime PM is request based, so only works for drivers
   that use request as their IO unit instead of those directly use bio's.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-pre-runtime-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_pre_runtime_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_pre_runtime_suspend</refname>
 <refpurpose>
     Pre runtime suspend check
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_pre_runtime_suspend </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the queue of the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will check if runtime suspend is allowed for the device
   by examining if there are any requests pending in the queue. If there
   are requests pending, the device can not be runtime suspended; otherwise,
   the queue's status will be updated to SUSPENDING and the driver can
   proceed to suspend the device.
   </para><para>

   For the not allowed case, we mark last busy for the device so that
   runtime PM core will try to autosuspend it some time later.
   </para><para>

   This function should be called near the start of the device's
   runtime_suspend callback.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0		- OK to runtime suspend the device
   -EBUSY	- Device should not be runtime suspended
</para>
</refsect1>
</refentry>

<refentry id="API-blk-post-runtime-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_post_runtime_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_post_runtime_suspend</refname>
 <refpurpose>
     Post runtime suspend processing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_post_runtime_suspend </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>int <parameter>err</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the queue of the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>err</parameter></term>
   <listitem>
    <para>
     return value of the device's runtime_suspend function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Update the queue's runtime status according to the return value of the
   device's runtime suspend function and mark last busy for the device so
   that PM core will try to auto suspend the device at a later time.
   </para><para>

   This function should be called near the end of the device's
   runtime_suspend callback.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-pre-runtime-resume">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_pre_runtime_resume</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_pre_runtime_resume</refname>
 <refpurpose>
     Pre runtime resume processing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_pre_runtime_resume </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the queue of the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Update the queue's runtime status to RESUMING in preparation for the
   runtime resume of the device.
   </para><para>

   This function should be called near the start of the device's
   runtime_resume callback.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-post-runtime-resume">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_post_runtime_resume</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_post_runtime_resume</refname>
 <refpurpose>
     Post runtime resume processing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_post_runtime_resume </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>int <parameter>err</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the queue of the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>err</parameter></term>
   <listitem>
    <para>
     return value of the device's runtime_resume function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Update the queue's runtime status according to the return value of the
   device's runtime_resume function. If it is successfully resumed, process
   the requests that are queued into the device's queue when it is resuming
   and then mark last busy and initiate autosuspend for it.
   </para><para>

   This function should be called near the end of the device's
   runtime_resume callback.
</para>
</refsect1>
</refentry>

<!-- block/blk-core.c -->
<refentry id="API---blk-run-queue-uncond">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__blk_run_queue_uncond</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__blk_run_queue_uncond</refname>
 <refpurpose>
  run a queue whether or not it has been stopped
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__blk_run_queue_uncond </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     The queue to run
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Invoke request handling on a queue if there are any pending requests.
   May be used to restart request handling after a request has completed.
   This variant runs the queue whether or not the queue has been
   stopped. Must be called with the queue lock held and interrupts
   disabled. See also <parameter>blk_run_queue</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API---blk-drain-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__blk_drain_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__blk_drain_queue</refname>
 <refpurpose>
     drain requests from request_queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__blk_drain_queue </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>bool <parameter>drain_all</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue to drain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drain_all</parameter></term>
   <listitem>
    <para>
     whether to drain all requests or only the ones w/ ELVPRIV
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drain requests from <parameter>q</parameter>.  If <parameter>drain_all</parameter> is set, all requests are drained.
   If not, only ELVPRIV requests are drained.  The caller is responsible
   for ensuring that no new requests which need to be drained are queued.
</para>
</refsect1>
</refentry>

<refentry id="API-rq-ioc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rq_ioc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rq_ioc</refname>
 <refpurpose>
     determine io_context for request allocation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct io_context * <function>rq_ioc </function></funcdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     request being allocated is for this bio (can be <constant>NULL</constant>)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Determine io_context to use for request allocation for <parameter>bio</parameter>.  May return
   <constant>NULL</constant> if <constant>current-</constant>&gt;io_context doesn't exist.
</para>
</refsect1>
</refentry>

<refentry id="API---get-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__get_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__get_request</refname>
 <refpurpose>
     get a free request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct request * <function>__get_request </function></funcdef>
   <paramdef>struct request_list * <parameter>rl</parameter></paramdef>
   <paramdef>int <parameter>rw_flags</parameter></paramdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rl</parameter></term>
   <listitem>
    <para>
     request list to allocate from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rw_flags</parameter></term>
   <listitem>
    <para>
     RW and SYNC flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     bio to allocate request for (can be <constant>NULL</constant>)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     allocation mask
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Get a free request from <parameter>q</parameter>.  This function may fail under memory
   pressure or if <parameter>q</parameter> is dead.
   </para><para>

   Must be called with <parameter>q</parameter>-&gt;queue_lock held and,
   Returns ERR_PTR on failure, with <parameter>q</parameter>-&gt;queue_lock held.
   Returns request pointer on success, with <parameter>q</parameter>-&gt;queue_lock *not held*.
</para>
</refsect1>
</refentry>

<refentry id="API-get-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_request</refname>
 <refpurpose>
     get a free request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct request * <function>get_request </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>int <parameter>rw_flags</parameter></paramdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     request_queue to allocate request from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rw_flags</parameter></term>
   <listitem>
    <para>
     RW and SYNC flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     bio to allocate request for (can be <constant>NULL</constant>)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     allocation mask
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Get a free request from <parameter>q</parameter>.  If <constant>__GFP_WAIT</constant> is set in <parameter>gfp_mask</parameter>, this
   function keeps retrying under memory pressure and fails iff <parameter>q</parameter> is dead.
   </para><para>

   Must be called with <parameter>q</parameter>-&gt;queue_lock held and,
   Returns ERR_PTR on failure, with <parameter>q</parameter>-&gt;queue_lock held.
   Returns request pointer on success, with <parameter>q</parameter>-&gt;queue_lock *not held*.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-attempt-plug-merge">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_attempt_plug_merge</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_attempt_plug_merge</refname>
 <refpurpose>
     try to merge with <constant>current</constant>'s plugged list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>blk_attempt_plug_merge </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
   <paramdef>unsigned int * <parameter>request_count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     request_queue new bio is being queued at
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     new bio being queued
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>request_count</parameter></term>
   <listitem>
    <para>
     out parameter for number of traversed plugged requests
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Determine whether <parameter>bio</parameter> being queued on <parameter>q</parameter> can be merged with a request
   on <constant>current</constant>'s plugged list.  Returns <constant>true</constant> if merge was successful,
   otherwise <constant>false</constant>.
   </para><para>

   Plugging coalesces IOs from the same issuer for the same purpose without
   going through <parameter>q</parameter>-&gt;queue_lock.  As such it's more of an issuing mechanism
   than scheduling, and the request, while may have elvpriv data, is not
   added on the elevator at this point.  In addition, we don't have
   reliable access to the elevator outside queue lock.  Only check basic
   merging parameters without querying the elevator.
   </para><para>

   Caller must ensure !blk_queue_nomerges(q) beforehand.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-end-bidi-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_end_bidi_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_end_bidi_request</refname>
 <refpurpose>
     Complete a bidi request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>blk_end_bidi_request </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
   <paramdef>unsigned int <parameter>nr_bytes</parameter></paramdef>
   <paramdef>unsigned int <parameter>bidi_bytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request to complete
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     <constant>0</constant> for success, &lt; <constant>0</constant> for error
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_bytes</parameter></term>
   <listitem>
    <para>
     number of bytes to complete <parameter>rq</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bidi_bytes</parameter></term>
   <listitem>
    <para>
     number of bytes to complete <parameter>rq</parameter>-&gt;next_rq
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Ends I/O on a number of bytes attached to <parameter>rq</parameter> and <parameter>rq</parameter>-&gt;next_rq.
   Drivers that supports bidi can safely call this member for any
   type of request, bidi or uni.  In the later case <parameter>bidi_bytes</parameter> is
   just ignored.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> - we are done with this request
   <constant>true</constant>  - still buffers pending for this request
</para>
</refsect1>
</refentry>

<refentry id="API---blk-end-bidi-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__blk_end_bidi_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__blk_end_bidi_request</refname>
 <refpurpose>
     Complete a bidi request with queue lock held
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>__blk_end_bidi_request </function></funcdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
   <paramdef>unsigned int <parameter>nr_bytes</parameter></paramdef>
   <paramdef>unsigned int <parameter>bidi_bytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request to complete
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     <constant>0</constant> for success, &lt; <constant>0</constant> for error
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_bytes</parameter></term>
   <listitem>
    <para>
     number of bytes to complete <parameter>rq</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bidi_bytes</parameter></term>
   <listitem>
    <para>
     number of bytes to complete <parameter>rq</parameter>-&gt;next_rq
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Identical to <function>blk_end_bidi_request</function> except that queue lock is
   assumed to be locked on entry and remains so on return.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   <constant>false</constant> - we are done with this request
   <constant>true</constant>  - still buffers pending for this request
</para>
</refsect1>
</refentry>

<!-- block/blk-map.c -->
<refentry id="API-blk-rq-map-user-iov">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_map_user_iov</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_map_user_iov</refname>
 <refpurpose>
  map user data to a request, for REQ_TYPE_BLOCK_PC usage
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_rq_map_user_iov </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>struct rq_map_data * <parameter>map_data</parameter></paramdef>
   <paramdef>const struct iov_iter * <parameter>iter</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     request queue where request should be inserted
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     request to map data to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>map_data</parameter></term>
   <listitem>
    <para>
     pointer to the rq_map_data holding pages (if necessary)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>iter</parameter></term>
   <listitem>
    <para>
     iovec iterator
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Data will be mapped directly for zero copy I/O, if possible. Otherwise
   a kernel bounce buffer is used.
   </para><para>

   A matching <function>blk_rq_unmap_user</function> must be issued at the end of I/O, while
   still in process context.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   The mapped bio may need to be bounced through <function>blk_queue_bounce</function>
   before being submitted to the device, as pages mapped may be out of
   reach. It's the callers responsibility to make sure this happens. The
   original bio must be passed back in to <function>blk_rq_unmap_user</function> for proper
   unmapping.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-rq-unmap-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_unmap_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_unmap_user</refname>
 <refpurpose>
     unmap a request with user data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_rq_unmap_user </function></funcdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     start of bio list
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unmap a rq previously mapped by <function>blk_rq_map_user</function>. The caller must
   supply the original rq-&gt;bio from the <function>blk_rq_map_user</function> return, since
   the I/O completion may have changed rq-&gt;bio.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-rq-map-kern">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_map_kern</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_map_kern</refname>
 <refpurpose>
     map kernel data to a request, for REQ_TYPE_BLOCK_PC usage
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_rq_map_kern </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>void * <parameter>kbuf</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     request queue where request should be inserted
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     request to fill
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kbuf</parameter></term>
   <listitem>
    <para>
     the kernel buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of user data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Data will be mapped directly if possible. Otherwise a bounce
   buffer is used. Can be called multiple times to append multiple
   buffers.
</para>
</refsect1>
</refentry>

<!-- block/blk-sysfs.c -->
<refentry id="API-blk-release-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_release_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_release_queue</refname>
 <refpurpose>
  release a <structname>struct request_queue</structname> when it is no longer needed
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_release_queue </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>
     the kobj belonging to the request queue to be released
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   blk_release_queue is the pair to <function>blk_init_queue</function> or
   <function>blk_queue_make_request</function>.  It should be called when a request queue is
   being released; typically when a block device is being de-registered.
   Currently, its primary task it to free all the <structname>struct request</structname>
   structures that were allocated to the queue and the queue itself.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   The low level driver must have finished any outstanding requests first
   via <function>blk_cleanup_queue</function>.
</para>
</refsect1>
</refentry>

<!-- block/blk-settings.c -->
<refentry id="API-blk-queue-prep-rq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_prep_rq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_prep_rq</refname>
 <refpurpose>
  set a prepare_request function for queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_prep_rq </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>prep_rq_fn * <parameter>pfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pfn</parameter></term>
   <listitem>
    <para>
     prepare_request function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It's possible for a queue to register a prepare_request callback which
   is invoked before the request is handed to the request_fn. The goal of
   the function is to prepare a request for I/O, it can be used to build a
   cdb from the request data for instance.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-unprep-rq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_unprep_rq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_unprep_rq</refname>
 <refpurpose>
     set an unprepare_request function for queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_unprep_rq </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unprep_rq_fn * <parameter>ufn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ufn</parameter></term>
   <listitem>
    <para>
     unprepare_request function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It's possible for a queue to register an unprepare_request callback
   which is invoked before the request is finally completed. The goal
   of the function is to deallocate any data that was allocated in the
   prepare_request callback.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-merge-bvec">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_merge_bvec</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_merge_bvec</refname>
 <refpurpose>
     set a merge_bvec function for queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_merge_bvec </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>merge_bvec_fn * <parameter>mbfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mbfn</parameter></term>
   <listitem>
    <para>
     merge_bvec_fn
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Usually queues have static limitations on the max sectors or segments that
   we can put in a request. Stacking drivers may have some settings that
   are dynamic, and thus we have to query the queue whether it is ok to
   add a new bio_vec to a bio at a given offset or not. If the block device
   has such limitations, it needs to register a merge_bvec_fn to control
   the size of bio's sent to it. Note that a block device *must* allow a
   single page to be added to an empty bio. The block device driver may want
   to use the <function>bio_split</function> function to deal with these bio's. By default
   no merge_bvec_fn is defined for a queue, and only the fixed limits are
   honored.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-set-default-limits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_set_default_limits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_set_default_limits</refname>
 <refpurpose>
     reset limits to default values
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_set_default_limits </function></funcdef>
   <paramdef>struct queue_limits * <parameter>lim</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>lim</parameter></term>
   <listitem>
    <para>
     the queue_limits structure to reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a queue_limit struct to its default state.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-set-stacking-limits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_set_stacking_limits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_set_stacking_limits</refname>
 <refpurpose>
     set default limits for stacking devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_set_stacking_limits </function></funcdef>
   <paramdef>struct queue_limits * <parameter>lim</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>lim</parameter></term>
   <listitem>
    <para>
     the queue_limits structure to reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a queue_limit struct to its default state. Should be used
   by stacking drivers like DM that have no internal limits.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-make-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_make_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_make_request</refname>
 <refpurpose>
     define an alternate make_request function for a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_make_request </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>make_request_fn * <parameter>mfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device to be affected
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mfn</parameter></term>
   <listitem>
    <para>
     the alternate make_request function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The normal way for <structname>struct bios</structname> to be passed to a device
   driver is for them to be collected into requests on a request
   queue, and then to allow the device driver to select requests
   off that queue when it is ready.  This works well for many block
   devices. However some block devices (typically virtual devices
   such as md or lvm) do not benefit from the processing on the
   request queue, and are served best by having the requests passed
   directly to them.  This can be achieved by providing a function
   to <function>blk_queue_make_request</function>.
</para>
</refsect1>
<refsect1>
<title>Caveat</title>
<para>
   The driver that does this *must* be able to deal appropriately
   with buffers in <quote>highmemory</quote>. This can be accomplished by either calling
   <function>__bio_kmap_atomic</function> to get a temporary kernel mapping, or by calling
   <function>blk_queue_bounce</function> to create a buffer in normal memory.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-bounce-limit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_bounce_limit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_bounce_limit</refname>
 <refpurpose>
     set bounce buffer limit for queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_bounce_limit </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>u64 <parameter>max_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_addr</parameter></term>
   <listitem>
    <para>
     the maximum address the device can handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Different hardware can have different requirements as to what pages
   it can do I/O directly to. A low level driver can call
   blk_queue_bounce_limit to have lower memory pages allocated as bounce
   buffers for doing I/O to pages residing above <parameter>max_addr</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-limits-max-hw-sectors">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_limits_max_hw_sectors</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_limits_max_hw_sectors</refname>
 <refpurpose>
     set hard and soft limit of max sectors for request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_limits_max_hw_sectors </function></funcdef>
   <paramdef>struct queue_limits * <parameter>limits</parameter></paramdef>
   <paramdef>unsigned int <parameter>max_hw_sectors</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>limits</parameter></term>
   <listitem>
    <para>
     the queue limits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_hw_sectors</parameter></term>
   <listitem>
    <para>
     max hardware sectors in the usual 512b unit
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enables a low level driver to set a hard upper limit,
   max_hw_sectors, on the size of requests.  max_hw_sectors is set by
   the device driver based upon the capabilities of the I/O
   controller.
   </para><para>

   max_sectors is a soft limit imposed by the block layer for
   filesystem type requests.  This value can be overridden on a
   per-device basis in /sys/block/&lt;device&gt;/queue/max_sectors_kb.
   The soft limit can not exceed max_hw_sectors.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-max-hw-sectors">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_max_hw_sectors</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_max_hw_sectors</refname>
 <refpurpose>
     set max sectors for a request for this queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_max_hw_sectors </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>max_hw_sectors</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_hw_sectors</parameter></term>
   <listitem>
    <para>
     max hardware sectors in the usual 512b unit
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   See description for <function>blk_limits_max_hw_sectors</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-chunk-sectors">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_chunk_sectors</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_chunk_sectors</refname>
 <refpurpose>
     set size of the chunk for this queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_chunk_sectors </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>chunk_sectors</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>chunk_sectors</parameter></term>
   <listitem>
    <para>
     chunk sectors in the usual 512b unit
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a driver doesn't want IOs to cross a given chunk size, it can set
   this limit and prevent merging across chunks. Note that the chunk size
   must currently be a power-of-2 in sectors. Also note that the block
   layer must accept a page worth of data at any offset. So if the
   crossing of chunks is a hard limitation in the driver, it must still be
   prepared to split single page bios.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-max-discard-sectors">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_max_discard_sectors</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_max_discard_sectors</refname>
 <refpurpose>
     set max sectors for a single discard
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_max_discard_sectors </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>max_discard_sectors</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_discard_sectors</parameter></term>
   <listitem>
    <para>
     maximum number of sectors to discard
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-blk-queue-max-write-same-sectors">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_max_write_same_sectors</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_max_write_same_sectors</refname>
 <refpurpose>
     set max sectors for a single write same
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_max_write_same_sectors </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>max_write_same_sectors</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_write_same_sectors</parameter></term>
   <listitem>
    <para>
     maximum number of sectors to write per command
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-blk-queue-max-segments">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_max_segments</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_max_segments</refname>
 <refpurpose>
     set max hw segments for a request for this queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_max_segments </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned short <parameter>max_segments</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_segments</parameter></term>
   <listitem>
    <para>
     max number of segments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enables a low level driver to set an upper limit on the number of
   hw data segments in a request.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-max-segment-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_max_segment_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_max_segment_size</refname>
 <refpurpose>
     set max segment size for blk_rq_map_sg
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_max_segment_size </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>max_size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_size</parameter></term>
   <listitem>
    <para>
     max size of segment in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enables a low level driver to set an upper limit on the size of a
   coalesced segment
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-logical-block-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_logical_block_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_logical_block_size</refname>
 <refpurpose>
     set logical block size for the queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_logical_block_size </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned short <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the logical block size, in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This should be set to the lowest possible block size that the
   storage device can address.  The default of 512 covers most
   hardware.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-physical-block-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_physical_block_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_physical_block_size</refname>
 <refpurpose>
     set physical block size for the queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_physical_block_size </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the physical block size, in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This should be set to the lowest possible sector size that the
   hardware can operate on without reverting to read-modify-write
   operations.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-alignment-offset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_alignment_offset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_alignment_offset</refname>
 <refpurpose>
     set physical block alignment offset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_alignment_offset </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     alignment offset in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Some devices are naturally misaligned to compensate for things like
   the legacy DOS partition table 63-sector offset.  Low-level drivers
   should call this function for devices whose first sector is not
   naturally aligned.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-limits-io-min">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_limits_io_min</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_limits_io_min</refname>
 <refpurpose>
     set minimum request size for a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_limits_io_min </function></funcdef>
   <paramdef>struct queue_limits * <parameter>limits</parameter></paramdef>
   <paramdef>unsigned int <parameter>min</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>limits</parameter></term>
   <listitem>
    <para>
     the queue limits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     smallest I/O size in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Some devices have an internal block size bigger than the reported
   hardware sector size.  This function can be used to signal the
   smallest I/O the device can perform without incurring a performance
   penalty.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-io-min">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_io_min</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_io_min</refname>
 <refpurpose>
     set minimum request size for the queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_io_min </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>min</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     smallest I/O size in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Storage devices may report a granularity or preferred minimum I/O
   size which is the smallest request the device can perform without
   incurring a performance penalty.  For disk drives this is often the
   physical block size.  For RAID arrays it is often the stripe chunk
   size.  A properly aligned multiple of minimum_io_size is the
   preferred request size for workloads where a high number of I/O
   operations is desired.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-limits-io-opt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_limits_io_opt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_limits_io_opt</refname>
 <refpurpose>
     set optimal request size for a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_limits_io_opt </function></funcdef>
   <paramdef>struct queue_limits * <parameter>limits</parameter></paramdef>
   <paramdef>unsigned int <parameter>opt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>limits</parameter></term>
   <listitem>
    <para>
     the queue limits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>opt</parameter></term>
   <listitem>
    <para>
     smallest I/O size in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Storage devices may report an optimal I/O size, which is the
   device's preferred unit for sustained I/O.  This is rarely reported
   for disk drives.  For RAID arrays it is usually the stripe width or
   the internal track size.  A properly aligned multiple of
   optimal_io_size is the preferred request size for workloads where
   sustained throughput is desired.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-io-opt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_io_opt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_io_opt</refname>
 <refpurpose>
     set optimal request size for the queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_io_opt </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>opt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>opt</parameter></term>
   <listitem>
    <para>
     optimal request size in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Storage devices may report an optimal I/O size, which is the
   device's preferred unit for sustained I/O.  This is rarely reported
   for disk drives.  For RAID arrays it is usually the stripe width or
   the internal track size.  A properly aligned multiple of
   optimal_io_size is the preferred request size for workloads where
   sustained throughput is desired.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-stack-limits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_stack_limits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_stack_limits</refname>
 <refpurpose>
     inherit underlying queue limits for stacked drivers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_stack_limits </function></funcdef>
   <paramdef>struct request_queue * <parameter>t</parameter></paramdef>
   <paramdef>struct request_queue * <parameter>b</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>t</parameter></term>
   <listitem>
    <para>
     the stacking driver (top)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>b</parameter></term>
   <listitem>
    <para>
     the underlying device (bottom)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-blk-stack-limits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_stack_limits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_stack_limits</refname>
 <refpurpose>
     adjust queue_limits for stacked devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_stack_limits </function></funcdef>
   <paramdef>struct queue_limits * <parameter>t</parameter></paramdef>
   <paramdef>struct queue_limits * <parameter>b</parameter></paramdef>
   <paramdef>sector_t <parameter>start</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>t</parameter></term>
   <listitem>
    <para>
     the stacking driver limits (top device)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>b</parameter></term>
   <listitem>
    <para>
     the underlying queue limits (bottom, component device)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     first data sector within component device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is used by stacking drivers like MD and DM to ensure
   that all component devices have compatible block sizes and
   alignments.  The stacking driver must provide a queue_limits
   struct (top) and then iteratively call the stacking function for
   all component (bottom) devices.  The stacking function will
   attempt to combine the values and ensure proper alignment.
   </para><para>

   Returns 0 if the top and bottom queue_limits are compatible.  The
   top device's block sizes and alignment offsets may be adjusted to
   ensure alignment with the bottom device. If no compatible sizes
   and alignments exist, -1 is returned and the resulting top
   queue_limits will have the misaligned flag set to indicate that
   the alignment_offset is undefined.
</para>
</refsect1>
</refentry>

<refentry id="API-bdev-stack-limits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bdev_stack_limits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bdev_stack_limits</refname>
 <refpurpose>
     adjust queue limits for stacked drivers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bdev_stack_limits </function></funcdef>
   <paramdef>struct queue_limits * <parameter>t</parameter></paramdef>
   <paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
   <paramdef>sector_t <parameter>start</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>t</parameter></term>
   <listitem>
    <para>
     the stacking driver limits (top device)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bdev</parameter></term>
   <listitem>
    <para>
     the component block_device (bottom)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     first data sector within component device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Merges queue limits for a top device and a block_device.  Returns
   0 if alignment didn't change.  Returns -1 if adding the bottom
   device caused misalignment.
</para>
</refsect1>
</refentry>

<refentry id="API-disk-stack-limits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_stack_limits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_stack_limits</refname>
 <refpurpose>
     adjust queue limits for stacked drivers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>disk_stack_limits </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
   <paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
   <paramdef>sector_t <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     MD/DM gendisk (top)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bdev</parameter></term>
   <listitem>
    <para>
     the underlying block device (bottom)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     offset to beginning of data within component device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Merges the limits for a top level gendisk and a bottom level
   block_device.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-dma-pad">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_dma_pad</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_dma_pad</refname>
 <refpurpose>
     set pad mask
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_dma_pad </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     pad mask
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set dma pad mask.
   </para><para>

   Appending pad buffer to a request modifies the last entry of a
   scatter list such that it includes the pad buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-update-dma-pad">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_update_dma_pad</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_update_dma_pad</refname>
 <refpurpose>
     update pad mask
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_update_dma_pad </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     pad mask
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Update dma pad mask.
   </para><para>

   Appending pad buffer to a request modifies the last entry of a
   scatter list such that it includes the pad buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-dma-drain">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_dma_drain</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_dma_drain</refname>
 <refpurpose>
     Set up a drain buffer for excess dma.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_queue_dma_drain </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>dma_drain_needed_fn * <parameter>dma_drain_needed</parameter></paramdef>
   <paramdef>void * <parameter>buf</parameter></paramdef>
   <paramdef>unsigned int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_drain_needed</parameter></term>
   <listitem>
    <para>
     fn which returns non-zero if drain is necessary
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     physically contiguous buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the buffer in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Some devices have excess DMA problems and can't simply discard (or
   zero fill) the unwanted piece of the transfer.  They have to have a
   real area of memory to transfer it into.  The use case for this is
   ATAPI devices in DMA mode.  If the packet command causes a transfer
   bigger than the transfer size some HBAs will lock up if there
   aren't DMA elements to contain the excess transfer.  What this API
   does is adjust the queue so that the buf is always appended
   silently to the scatterlist.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   This routine adjusts max_hw_segments to make room for appending
   the drain buffer.  If you call <function>blk_queue_max_segments</function> after calling
   this routine, you must set the limit to one fewer than your device
   can support otherwise there won't be room for the drain buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-segment-boundary">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_segment_boundary</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_segment_boundary</refname>
 <refpurpose>
     set boundary rules for segment merging
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_segment_boundary </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned long <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     the memory boundary mask
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-blk-queue-dma-alignment">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_dma_alignment</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_dma_alignment</refname>
 <refpurpose>
     set dma length and memory alignment
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_dma_alignment </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>int <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     alignment mask
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>description</title>
<para>
   set required memory and length alignment for direct dma transactions.
   this is used when building direct io requests for the queue.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-update-dma-alignment">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_update_dma_alignment</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_update_dma_alignment</refname>
 <refpurpose>
     update dma length and memory alignment
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_update_dma_alignment </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>int <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     alignment mask
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>description</title>
<para>
   update required memory and length alignment for direct dma transactions.
   If the requested alignment is larger than the current alignment, then
   the current queue alignment is updated to the new value, otherwise it
   is left alone.  The design of this is to allow multiple objects
   (driver, device, transport etc) to set their respective
   alignments without having them interfere.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_flush</refname>
 <refpurpose>
     configure queue's cache flush capability
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_flush </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>flush</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flush</parameter></term>
   <listitem>
    <para>
     0, REQ_FLUSH or REQ_FLUSH | REQ_FUA
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Tell block layer cache flush capability of <parameter>q</parameter>.  If it supports
   flushing, REQ_FLUSH should be set.  If it supports bypassing
   write cache for individual writes, REQ_FUA should be set.
</para>
</refsect1>
</refentry>

<!-- block/blk-exec.c -->
<refentry id="API-blk-execute-rq-nowait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_execute_rq_nowait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_execute_rq_nowait</refname>
 <refpurpose>
  insert a request into queue for execution
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_execute_rq_nowait </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct gendisk * <parameter>bd_disk</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>at_head</parameter></paramdef>
   <paramdef>rq_end_io_fn * <parameter>done</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue to insert the request in
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bd_disk</parameter></term>
   <listitem>
    <para>
     matching gendisk
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     request to insert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>at_head</parameter></term>
   <listitem>
    <para>
     insert request at head or tail of queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>done</parameter></term>
   <listitem>
    <para>
     I/O completion handler
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Insert a fully prepared request at the back of the I/O scheduler queue
   for execution.  Don't wait for completion.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   This function will invoke <parameter>done</parameter> directly if the queue is dead.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-execute-rq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_execute_rq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_execute_rq</refname>
 <refpurpose>
     insert a request into queue for execution
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_execute_rq </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct gendisk * <parameter>bd_disk</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>at_head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue to insert the request in
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bd_disk</parameter></term>
   <listitem>
    <para>
     matching gendisk
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     request to insert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>at_head</parameter></term>
   <listitem>
    <para>
     insert request at head or tail of queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Insert a fully prepared request at the back of the I/O scheduler queue
   for execution and wait for completion.
</para>
</refsect1>
</refentry>

<!-- block/blk-flush.c -->
<refentry id="API-blkdev-issue-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blkdev_issue_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blkdev_issue_flush</refname>
 <refpurpose>
  queue a flush
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blkdev_issue_flush </function></funcdef>
   <paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>sector_t * <parameter>error_sector</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bdev</parameter></term>
   <listitem>
    <para>
     blockdev to issue flush for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation flags (for bio_alloc)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error_sector</parameter></term>
   <listitem>
    <para>
     error sector
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Issue a flush for the block device in question. Caller can supply
   room for storing the error offset in case of a flush error, if they
   wish to. If WAIT flag is not passed then caller may check only what
   request was pushed in some internal queue for later handling.
</para>
</refsect1>
</refentry>

<!-- block/blk-lib.c -->
<refentry id="API-blkdev-issue-discard">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blkdev_issue_discard</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blkdev_issue_discard</refname>
 <refpurpose>
  queue a discard
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blkdev_issue_discard </function></funcdef>
   <paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
   <paramdef>sector_t <parameter>sector</parameter></paramdef>
   <paramdef>sector_t <parameter>nr_sects</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>unsigned long <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bdev</parameter></term>
   <listitem>
    <para>
     blockdev to issue discard for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sector</parameter></term>
   <listitem>
    <para>
     start sector
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_sects</parameter></term>
   <listitem>
    <para>
     number of sectors to discard
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation flags (for bio_alloc)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     BLKDEV_IFL_* flags to control behaviour
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Issue a discard request for the sectors in question.
</para>
</refsect1>
</refentry>

<refentry id="API-blkdev-issue-write-same">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blkdev_issue_write_same</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blkdev_issue_write_same</refname>
 <refpurpose>
     queue a write same operation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blkdev_issue_write_same </function></funcdef>
   <paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
   <paramdef>sector_t <parameter>sector</parameter></paramdef>
   <paramdef>sector_t <parameter>nr_sects</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>struct page * <parameter>page</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bdev</parameter></term>
   <listitem>
    <para>
     target blockdev
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sector</parameter></term>
   <listitem>
    <para>
     start sector
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_sects</parameter></term>
   <listitem>
    <para>
     number of sectors to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation flags (for bio_alloc)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>page</parameter></term>
   <listitem>
    <para>
     page containing data to write
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Issue a write same request for the sectors in question.
</para>
</refsect1>
</refentry>

<refentry id="API-blkdev-issue-zeroout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blkdev_issue_zeroout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blkdev_issue_zeroout</refname>
 <refpurpose>
     zero-fill a block range
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blkdev_issue_zeroout </function></funcdef>
   <paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
   <paramdef>sector_t <parameter>sector</parameter></paramdef>
   <paramdef>sector_t <parameter>nr_sects</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>bool <parameter>discard</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bdev</parameter></term>
   <listitem>
    <para>
     blockdev to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sector</parameter></term>
   <listitem>
    <para>
     start sector
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_sects</parameter></term>
   <listitem>
    <para>
     number of sectors to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     memory allocation flags (for bio_alloc)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>discard</parameter></term>
   <listitem>
    <para>
     whether to discard the block range
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Zero-fill a block range.  If the discard flag is set and the block
   device guarantees that subsequent READ operations to the block range
   in question will return zeroes, the blocks will be discarded. Should
   the discard request fail, if the discard flag is not set, or if
   discard_zeroes_data is not supported, this function will resort to
   zeroing the blocks manually, thus provisioning (allocating,
   anchoring) them. If the block device supports the WRITE SAME command
   <function>blkdev_issue_zeroout</function> will use it to optimize the process of
   clearing the block range. Otherwise the zeroing will be performed
   using regular WRITE calls.
</para>
</refsect1>
</refentry>

<!-- block/blk-tag.c -->
<refentry id="API-blk-queue-find-tag">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_find_tag</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_find_tag</refname>
 <refpurpose>
  find a request by its tag and queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct request * <function>blk_queue_find_tag </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>int <parameter>tag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     The request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tag</parameter></term>
   <listitem>
    <para>
     The tag of the request
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
   Should be used when a device returns a tag and you want to match
   it with a request.
   </para><para>

   no locks need be held.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-free-tags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_free_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_free_tags</refname>
 <refpurpose>
     release a given set of tag maintenance info
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_free_tags </function></funcdef>
   <paramdef>struct blk_queue_tag * <parameter>bqt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bqt</parameter></term>
   <listitem>
    <para>
     the tag map to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drop the reference count on <parameter>bqt</parameter> and frees it when the last reference
   is dropped.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-free-tags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_free_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_free_tags</refname>
 <refpurpose>
     release tag maintenance info
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_free_tags </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
   This is used to disable tagged queuing to a device, yet leave
   queue in function.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-init-tags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_init_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_init_tags</refname>
 <refpurpose>
     initialize the tag info for an external tag map
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct blk_queue_tag * <function>blk_init_tags </function></funcdef>
   <paramdef>int <parameter>depth</parameter></paramdef>
   <paramdef>int <parameter>alloc_policy</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>depth</parameter></term>
   <listitem>
    <para>
     the maximum queue depth supported
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alloc_policy</parameter></term>
   <listitem>
    <para>
     tag allocation policy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-blk-queue-init-tags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_init_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_init_tags</refname>
 <refpurpose>
     initialize the queue tag info
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_queue_init_tags </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>int <parameter>depth</parameter></paramdef>
   <paramdef>struct blk_queue_tag * <parameter>tags</parameter></paramdef>
   <paramdef>int <parameter>alloc_policy</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>depth</parameter></term>
   <listitem>
    <para>
     the maximum queue depth supported
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tags</parameter></term>
   <listitem>
    <para>
     the tag to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alloc_policy</parameter></term>
   <listitem>
    <para>
     tag allocation policy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Queue lock must be held here if the function is called to resize an
   existing map.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-resize-tags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_resize_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_resize_tags</refname>
 <refpurpose>
     change the queueing depth
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_queue_resize_tags </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>int <parameter>new_depth</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_depth</parameter></term>
   <listitem>
    <para>
     the new max command queueing depth
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
   Must be called with the queue lock held.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-end-tag">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_end_tag</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_end_tag</refname>
 <refpurpose>
     end tag operations for a request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_end_tag </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the request that has completed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Typically called when <function>end_that_request_first</function> returns <constant>0</constant>, meaning
   all transfers have been done for a request. It's important to call
   this function before <function>end_that_request_last</function>, as that will put the
   request back on the free list thus corrupting the internal tag list.
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
   queue lock must be held.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-start-tag">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_start_tag</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_start_tag</refname>
 <refpurpose>
     find a free tag and assign it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_queue_start_tag </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the block request that needs tagging
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This can either be used as a stand-alone helper, or possibly be
   assigned as the queue <structname>prep_rq_fn</structname> (in which case <structname>struct request</structname>
   automagically gets a tag assigned). Note that this function
   assumes that any type of request can be queued! if this is not
   true for your device, you must check the request type before
   calling this function.  The request will also be removed from
   the request queue, so it's the drivers responsibility to readd
   it if it should need to be restarted for some reason.
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
   queue lock must be held.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-invalidate-tags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_invalidate_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_invalidate_tags</refname>
 <refpurpose>
     invalidate all pending tags
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_invalidate_tags </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Hardware conditions may dictate a need to stop all pending requests.
   In this case, we will safely clear the block side of the tag queue and
   readd all requests to the request queue in the right order.
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
   queue lock must be held.
</para>
</refsect1>
</refentry>

<!-- block/blk-tag.c -->
<refentry id="API---blk-queue-free-tags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__blk_queue_free_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__blk_queue_free_tags</refname>
 <refpurpose>
  release tag maintenance info
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__blk_queue_free_tags </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue for the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
   <function>blk_cleanup_queue</function> will take care of calling this function, if tagging
   has been used. So there's no need to call this directly.
</para>
</refsect1>
</refentry>

<!-- block/blk-integrity.c -->
<refentry id="API-blk-rq-count-integrity-sg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_count_integrity_sg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_count_integrity_sg</refname>
 <refpurpose>
  Count number of integrity scatterlist elements
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_rq_count_integrity_sg </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     request queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     bio with integrity metadata attached
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the number of elements required in a
   scatterlist corresponding to the integrity metadata in a bio.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-rq-map-integrity-sg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_map_integrity_sg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_map_integrity_sg</refname>
 <refpurpose>
     Map integrity metadata into a scatterlist
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_rq_map_integrity_sg </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
   <paramdef>struct scatterlist * <parameter>sglist</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     request queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     bio with integrity metadata attached
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sglist</parameter></term>
   <listitem>
    <para>
     target scatterlist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Map the integrity vectors in request into a
   scatterlist.  The scatterlist must be big enough to hold all
   elements.  I.e. sized using <function>blk_rq_count_integrity_sg</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-integrity-compare">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_integrity_compare</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_integrity_compare</refname>
 <refpurpose>
     Compare integrity profile of two disks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_integrity_compare </function></funcdef>
   <paramdef>struct gendisk * <parameter>gd1</parameter></paramdef>
   <paramdef>struct gendisk * <parameter>gd2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>gd1</parameter></term>
   <listitem>
    <para>
     Disk to compare
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gd2</parameter></term>
   <listitem>
    <para>
     Disk to compare
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Meta-devices like DM and MD need to verify that all
   sub-devices use the same integrity format before advertising to
   upper layers that they can send/receive integrity metadata.  This
   function can be used to check whether two gendisk devices have
   compatible integrity formats.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-integrity-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_integrity_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_integrity_register</refname>
 <refpurpose>
     Register a gendisk as being integrity-capable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_integrity_register </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
   <paramdef>struct blk_integrity * <parameter>template</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     struct gendisk pointer to make integrity-aware
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>template</parameter></term>
   <listitem>
    <para>
     optional integrity profile to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When a device needs to advertise itself as being able
   to send/receive integrity metadata it must use this function to
   register the capability with the block layer.  The template is a
   blk_integrity struct with values appropriate for the underlying
   hardware.  If template is NULL the new profile is allocated but
   not filled out. See Documentation/block/data-integrity.txt.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-integrity-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_integrity_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_integrity_unregister</refname>
 <refpurpose>
     Remove block integrity profile
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_integrity_unregister </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     disk whose integrity profile to deallocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function frees all memory used by the block
   integrity profile.  To be called at device teardown.
</para>
</refsect1>
</refentry>

<!-- kernel/trace/blktrace.c -->
<refentry id="API-blk-trace-ioctl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_trace_ioctl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_trace_ioctl</refname>
 <refpurpose>
  handle the ioctls associated with tracing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_trace_ioctl </function></funcdef>
   <paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
   <paramdef>unsigned <parameter>cmd</parameter></paramdef>
   <paramdef>char __user * <parameter>arg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bdev</parameter></term>
   <listitem>
    <para>
     the block device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     the ioctl cmd
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>arg</parameter></term>
   <listitem>
    <para>
     the argument data, if any
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-blk-trace-shutdown">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_trace_shutdown</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_trace_shutdown</refname>
 <refpurpose>
     stop and cleanup trace structures
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_trace_shutdown </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue associated with the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-blk-add-trace-rq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_add_trace_rq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_add_trace_rq</refname>
 <refpurpose>
     Add a trace for a request oriented action
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_add_trace_rq </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>unsigned int <parameter>nr_bytes</parameter></paramdef>
   <paramdef>u32 <parameter>what</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue the io is for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the source request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_bytes</parameter></term>
   <listitem>
    <para>
     number of completed bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>what</parameter></term>
   <listitem>
    <para>
     the action
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Records an action against a request. Will log the bio offset + size.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-add-trace-bio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_add_trace_bio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_add_trace_bio</refname>
 <refpurpose>
     Add a trace for a bio oriented action
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_add_trace_bio </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
   <paramdef>u32 <parameter>what</parameter></paramdef>
   <paramdef>int <parameter>error</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue the io is for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     the source bio
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>what</parameter></term>
   <listitem>
    <para>
     the action
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     error, if any
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Records an action against a bio. Will log the bio offset + size.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-add-trace-bio-remap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_add_trace_bio_remap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_add_trace_bio_remap</refname>
 <refpurpose>
     Add a trace for a bio-remap operation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_add_trace_bio_remap </function></funcdef>
   <paramdef>void * <parameter>ignore</parameter></paramdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct bio * <parameter>bio</parameter></paramdef>
   <paramdef>dev_t <parameter>dev</parameter></paramdef>
   <paramdef>sector_t <parameter>from</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ignore</parameter></term>
   <listitem>
    <para>
     trace callback data parameter (not used)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue the io is for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bio</parameter></term>
   <listitem>
    <para>
     the source bio
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     target device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     source sector
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Device mapper or raid target sometimes need to split a bio because
   it spans a stripe (or similar). Add a trace for that action.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-add-trace-rq-remap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_add_trace_rq_remap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_add_trace_rq_remap</refname>
 <refpurpose>
     Add a trace for a request-remap operation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_add_trace_rq_remap </function></funcdef>
   <paramdef>void * <parameter>ignore</parameter></paramdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>dev_t <parameter>dev</parameter></paramdef>
   <paramdef>sector_t <parameter>from</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ignore</parameter></term>
   <listitem>
    <para>
     trace callback data parameter (not used)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue the io is for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     the source request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     target device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     source sector
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Device mapper remaps request to other devices.
   Add a trace for that action.
</para>
</refsect1>
</refentry>

<!-- block/genhd.c -->
<refentry id="API-blk-mangle-minor">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_mangle_minor</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_mangle_minor</refname>
 <refpurpose>
  scatter minor numbers apart
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_mangle_minor </function></funcdef>
   <paramdef>int <parameter>minor</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>minor</parameter></term>
   <listitem>
    <para>
     minor number to mangle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Scatter consecutively allocated <parameter>minor</parameter> number apart if MANGLE_DEVT
   is enabled.  Mangling twice gives the original value.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Mangled value.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Don't care.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-alloc-devt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_alloc_devt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_alloc_devt</refname>
 <refpurpose>
     allocate a dev_t for a partition
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_alloc_devt </function></funcdef>
   <paramdef>struct hd_struct * <parameter>part</parameter></paramdef>
   <paramdef>dev_t * <parameter>devt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>part</parameter></term>
   <listitem>
    <para>
     partition to allocate dev_t for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devt</parameter></term>
   <listitem>
    <para>
     out parameter for resulting dev_t
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a dev_t for block device.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 on success, allocated dev_t is returned in *<parameter>devt</parameter>.  -errno on
   failure.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Might sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-free-devt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_free_devt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_free_devt</refname>
 <refpurpose>
     free a dev_t
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_free_devt </function></funcdef>
   <paramdef>dev_t <parameter>devt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>devt</parameter></term>
   <listitem>
    <para>
     dev_t to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free <parameter>devt</parameter> which was allocated using <function>blk_alloc_devt</function>.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Might sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-disk-replace-part-tbl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_replace_part_tbl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_replace_part_tbl</refname>
 <refpurpose>
     replace disk-&gt;part_tbl in RCU-safe way
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>disk_replace_part_tbl </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
   <paramdef>struct disk_part_tbl * <parameter>new_ptbl</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     disk to replace part_tbl for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_ptbl</parameter></term>
   <listitem>
    <para>
     new part_tbl to install
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Replace disk-&gt;part_tbl with <parameter>new_ptbl</parameter> in RCU-safe way.  The
   original ptbl is freed using RCU callback.
</para>
</refsect1>
<refsect1>
<title>LOCKING</title>
<para>
   Matching bd_mutx locked.
</para>
</refsect1>
</refentry>

<refentry id="API-disk-expand-part-tbl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_expand_part_tbl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_expand_part_tbl</refname>
 <refpurpose>
     expand disk-&gt;part_tbl
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>disk_expand_part_tbl </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
   <paramdef>int <parameter>partno</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     disk to expand part_tbl for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>partno</parameter></term>
   <listitem>
    <para>
     expand such that this partno can fit in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Expand disk-&gt;part_tbl such that <parameter>partno</parameter> can fit in.  disk-&gt;part_tbl
   uses RCU to allow unlocked dereferencing for stats and other stuff.
</para>
</refsect1>
<refsect1>
<title>LOCKING</title>
<para>
   Matching bd_mutex locked, might sleep.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 on success, -errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-disk-block-events">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_block_events</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_block_events</refname>
 <refpurpose>
     block and flush disk event checking
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>disk_block_events </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     disk to block events for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   On return from this function, it is guaranteed that event checking
   isn't in progress and won't happen until unblocked by
   <function>disk_unblock_events</function>.  Events blocking is counted and the actual
   unblocking happens after the matching number of unblocks are done.
   </para><para>

   Note that this intentionally does not block event checking from
   <function>disk_clear_events</function>.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Might sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-disk-unblock-events">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_unblock_events</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_unblock_events</refname>
 <refpurpose>
     unblock disk event checking
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>disk_unblock_events </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     disk to unblock events for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Undo <function>disk_block_events</function>.  When the block count reaches zero, it
   starts events polling if configured.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Don't care.  Safe to call from irq context.
</para>
</refsect1>
</refentry>

<refentry id="API-disk-flush-events">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_flush_events</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_flush_events</refname>
 <refpurpose>
     schedule immediate event checking and flushing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>disk_flush_events </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
   <paramdef>unsigned int <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     disk to check and flush events for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     events to flush
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Schedule immediate event checking on <parameter>disk</parameter> if not blocked.  Events in
   <parameter>mask</parameter> are scheduled to be cleared from the driver.  Note that this
   doesn't clear the events from <parameter>disk</parameter>-&gt;ev.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   If <parameter>mask</parameter> is non-zero must be called with bdev-&gt;bd_mutex held.
</para>
</refsect1>
</refentry>

<refentry id="API-disk-clear-events">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_clear_events</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_clear_events</refname>
 <refpurpose>
     synchronously check, clear and return pending events
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>disk_clear_events </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
   <paramdef>unsigned int <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     disk to fetch and clear events from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     mask of events to be fetched and cleared
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Disk events are synchronously checked and pending events in <parameter>mask</parameter>
   are cleared and returned.  This ignores the block count.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Might sleep.
</para>
</refsect1>
</refentry>

<!-- block/genhd.c -->
<refentry id="API-disk-get-part">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_get_part</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_get_part</refname>
 <refpurpose>
  get partition
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct hd_struct * <function>disk_get_part </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
   <paramdef>int <parameter>partno</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     disk to look partition from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>partno</parameter></term>
   <listitem>
    <para>
     partition number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Look for partition <parameter>partno</parameter> from <parameter>disk</parameter>.  If found, increment
   reference count and return it.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Don't care.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to the found partition on success, NULL if not found.
</para>
</refsect1>
</refentry>

<refentry id="API-disk-part-iter-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_part_iter_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_part_iter_init</refname>
 <refpurpose>
     initialize partition iterator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>disk_part_iter_init </function></funcdef>
   <paramdef>struct disk_part_iter * <parameter>piter</parameter></paramdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>piter</parameter></term>
   <listitem>
    <para>
     iterator to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     disk to iterate over
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     DISK_PITER_* flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize <parameter>piter</parameter> so that it iterates over partitions of <parameter>disk</parameter>.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Don't care.
</para>
</refsect1>
</refentry>

<refentry id="API-disk-part-iter-next">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_part_iter_next</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_part_iter_next</refname>
 <refpurpose>
     proceed iterator to the next partition and return it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct hd_struct * <function>disk_part_iter_next </function></funcdef>
   <paramdef>struct disk_part_iter * <parameter>piter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>piter</parameter></term>
   <listitem>
    <para>
     iterator of interest
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Proceed <parameter>piter</parameter> to the next partition and return it.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Don't care.
</para>
</refsect1>
</refentry>

<refentry id="API-disk-part-iter-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_part_iter_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_part_iter_exit</refname>
 <refpurpose>
     finish up partition iteration
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>disk_part_iter_exit </function></funcdef>
   <paramdef>struct disk_part_iter * <parameter>piter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>piter</parameter></term>
   <listitem>
    <para>
     iter of interest
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called when iteration is over.  Cleans up <parameter>piter</parameter>.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Don't care.
</para>
</refsect1>
</refentry>

<refentry id="API-disk-map-sector-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disk_map_sector_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>disk_map_sector_rcu</refname>
 <refpurpose>
     map sector to partition
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct hd_struct * <function>disk_map_sector_rcu </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
   <paramdef>sector_t <parameter>sector</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     gendisk of interest
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sector</parameter></term>
   <listitem>
    <para>
     sector to map
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Find out which partition <parameter>sector</parameter> maps to on <parameter>disk</parameter>.  This is
   primarily used for stats accounting.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   RCU read locked.  The returned partition pointer is valid only
   while preemption is disabled.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Found partition on success, part0 is returned if no partition matches
</para>
</refsect1>
</refentry>

<refentry id="API-register-blkdev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_blkdev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_blkdev</refname>
 <refpurpose>
     register a new block device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_blkdev </function></funcdef>
   <paramdef>unsigned int <parameter>major</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>major</parameter></term>
   <listitem>
    <para>
     the requested major device number [1..255]. If <parameter>major</parameter>=0, try to
     allocate any unused major number.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the name of the new block device as a zero terminated string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The <parameter>name</parameter> must be unique within the system.
   </para><para>

   The return value depends on the <parameter>major</parameter> input parameter.
   - if a major device number was requested in range [1..255] then the
   function returns zero on success, or a negative error code
   - if any unused major number was requested with <parameter>major</parameter>=0 parameter
   then the return value is the allocated major number in range
   [1..255] or a negative error code otherwise
</para>
</refsect1>
</refentry>

<refentry id="API-add-disk">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>add_disk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>add_disk</refname>
 <refpurpose>
     add partitioning information to kernel list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>add_disk </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     per-device partitioning information
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function registers the partitioning information in <parameter>disk</parameter>
   with the kernel.
</para>
</refsect1>
<refsect1>
<title>FIXME</title>
<para>
   error handling
</para>
</refsect1>
</refentry>

<refentry id="API-get-gendisk">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_gendisk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_gendisk</refname>
 <refpurpose>
     get partitioning information for a given device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct gendisk * <function>get_gendisk </function></funcdef>
   <paramdef>dev_t <parameter>devt</parameter></paramdef>
   <paramdef>int * <parameter>partno</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>devt</parameter></term>
   <listitem>
    <para>
     device to get partitioning information for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>partno</parameter></term>
   <listitem>
    <para>
     returned partition index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function gets the structure containing partitioning
   information for the given device <parameter>devt</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-bdget-disk">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bdget_disk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bdget_disk</refname>
 <refpurpose>
     do <function>bdget</function> by gendisk and partition number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct block_device * <function>bdget_disk </function></funcdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
   <paramdef>int <parameter>partno</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     gendisk of interest
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>partno</parameter></term>
   <listitem>
    <para>
     partition number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Find partition <parameter>partno</parameter> from <parameter>disk</parameter>, do <function>bdget</function> on it.
</para>
</refsect1>
<refsect1>
<title>CONTEXT</title>
<para>
   Don't care.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Resulting block_device on success, NULL on failure.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="chrdev">
	<title>Char devices</title>
<!-- fs/char_dev.c -->
<refentry id="API-register-chrdev-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_chrdev_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_chrdev_region</refname>
 <refpurpose>
  register a range of device numbers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_chrdev_region </function></funcdef>
   <paramdef>dev_t <parameter>from</parameter></paramdef>
   <paramdef>unsigned <parameter>count</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     the first in the desired range of device numbers; must include
     the major number.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of consecutive device numbers required
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the name of the device or driver.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return value is zero on success, a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-alloc-chrdev-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>alloc_chrdev_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>alloc_chrdev_region</refname>
 <refpurpose>
     register a range of char device numbers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>alloc_chrdev_region </function></funcdef>
   <paramdef>dev_t * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>baseminor</parameter></paramdef>
   <paramdef>unsigned <parameter>count</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>
     output parameter for first assigned number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>baseminor</parameter></term>
   <listitem>
    <para>
     first of the requested range of minor numbers
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of minor numbers required
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the name of the associated device or driver
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates a range of char device numbers.  The major number will be
   chosen dynamically, and returned (along with the first minor number)
   in <parameter>dev</parameter>.  Returns zero or a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API---register-chrdev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__register_chrdev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__register_chrdev</refname>
 <refpurpose>
     create and register a cdev occupying a range of minors
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__register_chrdev </function></funcdef>
   <paramdef>unsigned int <parameter>major</parameter></paramdef>
   <paramdef>unsigned int <parameter>baseminor</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>major</parameter></term>
   <listitem>
    <para>
     major device number or 0 for dynamic allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>baseminor</parameter></term>
   <listitem>
    <para>
     first of the requested range of minor numbers
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of minor numbers required
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of this range of devices
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fops</parameter></term>
   <listitem>
    <para>
     file operations associated with this devices
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If <parameter>major</parameter> == 0 this functions will dynamically allocate a major and return
   its number.
   </para><para>

   If <parameter>major</parameter> &gt; 0 this function will attempt to reserve a device with the given
   major number and will return zero on success.
   </para><para>

   Returns a -ve errno on failure.
   </para><para>

   The name of this device has nothing to do with the name of the device in
   /dev. It only helps to keep track of the different owners of devices. If
   your module name has only one type of devices it's ok to use e.g. the name
   of the module here.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-chrdev-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_chrdev_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_chrdev_region</refname>
 <refpurpose>
     return a range of device numbers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_chrdev_region </function></funcdef>
   <paramdef>dev_t <parameter>from</parameter></paramdef>
   <paramdef>unsigned <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     the first in the range of numbers to unregister
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of device numbers to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will unregister a range of <parameter>count</parameter> device numbers,
   starting with <parameter>from</parameter>.  The caller should normally be the one who
   allocated those numbers in the first place...
</para>
</refsect1>
</refentry>

<refentry id="API---unregister-chrdev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__unregister_chrdev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__unregister_chrdev</refname>
 <refpurpose>
     unregister and destroy a cdev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__unregister_chrdev </function></funcdef>
   <paramdef>unsigned int <parameter>major</parameter></paramdef>
   <paramdef>unsigned int <parameter>baseminor</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>major</parameter></term>
   <listitem>
    <para>
     major device number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>baseminor</parameter></term>
   <listitem>
    <para>
     first of the range of minor numbers
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of minor numbers this cdev is occupying
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of this range of devices
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregister and destroy the cdev occupying the region described by
   <parameter>major</parameter>, <parameter>baseminor</parameter> and <parameter>count</parameter>.  This function undoes what
   <function>__register_chrdev</function> did.
</para>
</refsect1>
</refentry>

<refentry id="API-cdev-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cdev_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cdev_add</refname>
 <refpurpose>
     add a char device to the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>cdev_add </function></funcdef>
   <paramdef>struct cdev * <parameter>p</parameter></paramdef>
   <paramdef>dev_t <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     the cdev structure for the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the first device number for which this device is responsible
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of consecutive minor numbers corresponding to this
     device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>cdev_add</function> adds the device represented by <parameter>p</parameter> to the system, making it
   live immediately.  A negative error code is returned on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-cdev-del">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cdev_del</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cdev_del</refname>
 <refpurpose>
     remove a cdev from the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>cdev_del </function></funcdef>
   <paramdef>struct cdev * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     the cdev structure to be removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>cdev_del</function> removes <parameter>p</parameter> from the system, possibly freeing the structure
   itself.
</para>
</refsect1>
</refentry>

<refentry id="API-cdev-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cdev_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cdev_alloc</refname>
 <refpurpose>
     allocate a cdev structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct cdev * <function>cdev_alloc </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>

   Allocates and returns a cdev structure, or NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-cdev-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cdev_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cdev_init</refname>
 <refpurpose>
     initialize a cdev structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>cdev_init </function></funcdef>
   <paramdef>struct cdev * <parameter>cdev</parameter></paramdef>
   <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cdev</parameter></term>
   <listitem>
    <para>
     the structure to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fops</parameter></term>
   <listitem>
    <para>
     the file_operations for this device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initializes <parameter>cdev</parameter>, remembering <parameter>fops</parameter>, making it ready to add to the
   system with <function>cdev_add</function>.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="miscdev">
     <title>Miscellaneous Devices</title>
<!-- drivers/char/misc.c -->
<refentry id="API-misc-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>misc_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>misc_register</refname>
 <refpurpose>
  register a miscellaneous device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>misc_register </function></funcdef>
   <paramdef>struct miscdevice * <parameter>misc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>misc</parameter></term>
   <listitem>
    <para>
     device structure
     </para><para>

     Register a miscellaneous device with the kernel. If the minor
     number is set to <constant>MISC_DYNAMIC_MINOR</constant> a minor number is assigned
     and placed in the minor field of the structure. For other cases
     the minor number requested is used.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The structure passed is linked into the kernel and may not be
   destroyed until it has been unregistered. By default, an <function>open</function>
   syscall to the device sets file-&gt;private_data to point to the
   structure. Drivers don't need open in fops for this.
   </para><para>

   A zero is returned on success and a negative errno code for
   failure.
</para>
</refsect1>
</refentry>

<refentry id="API-misc-deregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>misc_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>misc_deregister</refname>
 <refpurpose>
     unregister a miscellaneous device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>misc_deregister </function></funcdef>
   <paramdef>struct miscdevice * <parameter>misc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>misc</parameter></term>
   <listitem>
    <para>
     device to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregister a miscellaneous device that was previously
   successfully registered with <function>misc_register</function>. Success
   is indicated by a zero return, a negative errno code
   indicates an error.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="clk">
     <title>Clock Framework</title>

     <para>
	The clock framework defines programming interfaces to support
	software management of the system clock tree.
	This framework is widely used with System-On-Chip (SOC) platforms
	to support power management and various devices which may need
	custom clock rates.
	Note that these "clocks" don't relate to timekeeping or real
	time clocks (RTCs), each of which have separate frameworks.
	These <structname>struct clk</structname> instances may be used
	to manage for example a 96 MHz signal that is used to shift bits
	into and out of peripherals or busses, or otherwise trigger
	synchronous state machine transitions in system hardware.
     </para>

     <para>
	Power management is supported by explicit software clock gating:
	unused clocks are disabled, so the system doesn't waste power
	changing the state of transistors that aren't in active use.
	On some systems this may be backed by hardware clock gating,
	where clocks are gated without being disabled in software.
	Sections of chips that are powered but not clocked may be able
	to retain their last state.
	This low power state is often called a <emphasis>retention
	mode</emphasis>.
	This mode still incurs leakage currents, especially with finer
	circuit geometries, but for CMOS circuits power is mostly used
	by clocked state changes.
     </para>

     <para>
	Power-aware drivers only enable their clocks when the device
	they manage is in active use.  Also, system sleep states often
	differ according to which clock domains are active:  while a
	"standby" state may allow wakeup from several active domains, a
	"mem" (suspend-to-RAM) state may require a more wholesale shutdown
	of clocks derived from higher speed PLLs and oscillators, limiting
	the number of possible wakeup event sources.  A driver's suspend
	method may need to be aware of system-specific clock constraints
	on the target sleep state.
     </para>

     <para>
        Some platforms support programmable clock generators.  These
	can be used by external chips of various kinds, such as other
	CPUs, multimedia codecs, and devices with strict requirements
	for interface clocking.
     </para>

<!-- include/linux/clk.h -->
<refentry id="API-struct-clk-notifier">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct clk_notifier</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct clk_notifier</refname>
 <refpurpose>
  associate a clk with a notifier
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct clk_notifier {
  struct clk * clk;
  struct srcu_notifier_head notifier_head;
  struct list_head node;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>clk</term>
      <listitem><para>
struct clk * to associate the notifier with
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>notifier_head</term>
      <listitem><para>
a blocking_notifier_head for this clk
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>node</term>
      <listitem><para>
linked list pointers
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   A list of struct clk_notifier is maintained by the notifier code.
   An entry is created whenever code registers the first notifier on a
   particular <parameter>clk</parameter>.  Future notifiers on that <parameter>clk</parameter> are added to the
   <parameter>notifier_head</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-clk-notifier-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct clk_notifier_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct clk_notifier_data</refname>
 <refpurpose>
     rate data to pass to the notifier callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct clk_notifier_data {
  struct clk * clk;
  unsigned long old_rate;
  unsigned long new_rate;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>clk</term>
      <listitem><para>
   struct clk * being changed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>old_rate</term>
      <listitem><para>
   previous rate of this clk
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>new_rate</term>
      <listitem><para>
   new rate of this clk
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   For a pre-notifier, old_rate is the clk's rate before this rate
   change, and new_rate is what the rate will be in the future.  For a
   post-notifier, old_rate and new_rate are both set to the clk's
   current rate (this was done to optimize the implementation).
</para>
</refsect1>
</refentry>

<refentry id="API-clk-notifier-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_notifier_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_notifier_register</refname>
 <refpurpose>
     change notifier callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_notifier_register </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
   <paramdef>struct notifier_block * <parameter>nb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock whose rate we are interested in
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nb</parameter></term>
   <listitem>
    <para>
     notifier block with callback function pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>ProTip</title>
<para>
   debugging across notifier chains can be frustrating. Make sure that
   your notifier callback function prints a nice big warning in case of
   failure.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-notifier-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_notifier_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_notifier_unregister</refname>
 <refpurpose>
     change notifier callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_notifier_unregister </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
   <paramdef>struct notifier_block * <parameter>nb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock whose rate we are no longer interested in
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nb</parameter></term>
   <listitem>
    <para>
     notifier block which will be unregistered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-clk-get-accuracy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_get_accuracy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_get_accuracy</refname>
 <refpurpose>
     obtain the clock accuracy in ppb (parts per billion) for a clock source.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>clk_get_accuracy </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This gets the clock source accuracy expressed in ppb.
   A perfect clock returns 0.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-set-phase">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_set_phase</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_set_phase</refname>
 <refpurpose>
     adjust the phase shift of a clock signal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_set_phase </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
   <paramdef>int <parameter>degrees</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock signal source
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>degrees</parameter></term>
   <listitem>
    <para>
     number of degrees the signal is shifted
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Shifts the phase of a clock signal by the specified degrees. Returns 0 on
   success, -EERROR otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-get-phase">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_get_phase</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_get_phase</refname>
 <refpurpose>
     return the phase shift of a clock signal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_get_phase </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock signal source
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the phase shift of a clock node in degrees, otherwise returns
   -EERROR.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-is-match">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_is_match</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_is_match</refname>
 <refpurpose>
     check if two clk's point to the same hardware clock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>clk_is_match </function></funcdef>
   <paramdef>const struct clk * <parameter>p</parameter></paramdef>
   <paramdef>const struct clk * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     clk compared against q
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     clk compared against p
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if the two struct clk pointers both point to the same hardware
   clock node. Put differently, returns true if struct clk *p and struct clk *q
   share the same struct clk_core object.
   </para><para>

   Returns false otherwise. Note that two NULL clks are treated as matching.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-prepare">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_prepare</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_prepare</refname>
 <refpurpose>
     prepare a clock source
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_prepare </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This prepares the clock source for use.
   </para><para>

   Must not be called from within atomic context.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-unprepare">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_unprepare</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_unprepare</refname>
 <refpurpose>
     undo preparation of a clock source
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>clk_unprepare </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This undoes a previously prepared clock.  The caller must balance
   the number of prepare and unprepare calls.
   </para><para>

   Must not be called from within atomic context.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_get</refname>
 <refpurpose>
     lookup and obtain a reference to a clock producer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct clk * <function>clk_get </function></funcdef>
   <paramdef>struct device * <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>
     device for clock <quote>consumer</quote>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     clock consumer ID
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a struct clk corresponding to the clock producer, or
   valid <function>IS_ERR</function> condition containing errno.  The implementation
   uses <parameter>dev</parameter> and <parameter>id</parameter> to determine the clock consumer, and thereby
   the clock producer.  (IOW, <parameter>id</parameter> may be identical strings, but
   clk_get may return different clock producers depending on <parameter>dev</parameter>.)
   </para><para>

   Drivers must assume that the clock source is not enabled.
   </para><para>

   clk_get should not be called from within interrupt context.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-clk-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_clk_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_clk_get</refname>
 <refpurpose>
     lookup and obtain a managed reference to a clock producer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct clk * <function>devm_clk_get </function></funcdef>
   <paramdef>struct device * <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>
     device for clock <quote>consumer</quote>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     clock consumer ID
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a struct clk corresponding to the clock producer, or
   valid <function>IS_ERR</function> condition containing errno.  The implementation
   uses <parameter>dev</parameter> and <parameter>id</parameter> to determine the clock consumer, and thereby
   the clock producer.  (IOW, <parameter>id</parameter> may be identical strings, but
   clk_get may return different clock producers depending on <parameter>dev</parameter>.)
   </para><para>

   Drivers must assume that the clock source is not enabled.
   </para><para>

   devm_clk_get should not be called from within interrupt context.
   </para><para>

   The clock will automatically be freed when the device is unbound
   from the bus.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_enable</refname>
 <refpurpose>
     inform the system when the clock source should be running.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_enable </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the clock can not be enabled/disabled, this should return success.
   </para><para>

   May be called from atomic contexts.
   </para><para>

   Returns success (0) or negative errno.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_disable</refname>
 <refpurpose>
     inform the system when the clock source is no longer required.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>clk_disable </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Inform the system that a clock source is no longer required by
   a driver and may be shut down.
   </para><para>

   May be called from atomic contexts.
</para>
</refsect1>
<refsect1>
<title>Implementation detail</title>
<para>
   if the clock source is shared between
   multiple drivers, <function>clk_enable</function> calls must be balanced by the
   same number of <function>clk_disable</function> calls for the clock source to be
   disabled.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-get-rate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_get_rate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_get_rate</refname>
 <refpurpose>
     obtain the current clock rate (in Hz) for a clock source. This is only valid once the clock source has been enabled.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>clk_get_rate </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-clk-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_put</refname>
 <refpurpose>
     "free" the clock source
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>clk_put </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   drivers must ensure that all clk_enable calls made on this
   clock source are balanced by clk_disable calls prior to calling
   this function.
   </para><para>

   clk_put should not be called from within interrupt context.
</para>
</refsect1>
</refentry>

<refentry id="API-devm-clk-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>devm_clk_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>devm_clk_put</refname>
 <refpurpose>
     "free" a managed clock source
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>devm_clk_put </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device used to acquire the clock
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source acquired with <function>devm_clk_get</function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   drivers must ensure that all clk_enable calls made on this
   clock source are balanced by clk_disable calls prior to calling
   this function.
   </para><para>

   clk_put should not be called from within interrupt context.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-round-rate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_round_rate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_round_rate</refname>
 <refpurpose>
     adjust a rate to the exact rate a clock can provide
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>clk_round_rate </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
   <paramdef>unsigned long <parameter>rate</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rate</parameter></term>
   <listitem>
    <para>
     desired clock rate in Hz
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns rounded clock rate in Hz, or negative errno.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-set-rate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_set_rate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_set_rate</refname>
 <refpurpose>
     set the clock rate for a clock source
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_set_rate </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
   <paramdef>unsigned long <parameter>rate</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rate</parameter></term>
   <listitem>
    <para>
     desired clock rate in Hz
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns success (0) or negative errno.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-has-parent">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_has_parent</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_has_parent</refname>
 <refpurpose>
     check if a clock is a possible parent for another
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>clk_has_parent </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
   <paramdef>struct clk * <parameter>parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent clock source
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can be used in drivers that need to check that a clock can be
   the parent of another without actually changing the parent.
   </para><para>

   Returns true if <parameter>parent</parameter> is a possible parent for <parameter>clk</parameter>, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-set-rate-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_set_rate_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_set_rate_range</refname>
 <refpurpose>
     set a rate range for a clock source
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_set_rate_range </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
   <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>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     desired minimum clock rate in Hz, inclusive
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     desired maximum clock rate in Hz, inclusive
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns success (0) or negative errno.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-set-min-rate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_set_min_rate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_set_min_rate</refname>
 <refpurpose>
     set a minimum clock rate for a clock source
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_set_min_rate </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
   <paramdef>unsigned long <parameter>rate</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rate</parameter></term>
   <listitem>
    <para>
     desired minimum clock rate in Hz, inclusive
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns success (0) or negative errno.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-set-max-rate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_set_max_rate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_set_max_rate</refname>
 <refpurpose>
     set a maximum clock rate for a clock source
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_set_max_rate </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
   <paramdef>unsigned long <parameter>rate</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rate</parameter></term>
   <listitem>
    <para>
     desired maximum clock rate in Hz, inclusive
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns success (0) or negative errno.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-set-parent">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_set_parent</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_set_parent</refname>
 <refpurpose>
     set the parent clock source for this clock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_set_parent </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
   <paramdef>struct clk * <parameter>parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     parent clock source
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns success (0) or negative errno.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-get-parent">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_get_parent</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_get_parent</refname>
 <refpurpose>
     get the parent clock source for this clock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct clk * <function>clk_get_parent </function></funcdef>
   <paramdef>struct clk * <parameter>clk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clk</parameter></term>
   <listitem>
    <para>
     clock source
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns struct clk corresponding to parent clock source, or
   valid <function>IS_ERR</function> condition containing errno.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-get-sys">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_get_sys</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_get_sys</refname>
 <refpurpose>
     get a clock based upon the device name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct clk * <function>clk_get_sys </function></funcdef>
   <paramdef>const char * <parameter>dev_id</parameter></paramdef>
   <paramdef>const char * <parameter>con_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_id</parameter></term>
   <listitem>
    <para>
     device name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>con_id</parameter></term>
   <listitem>
    <para>
     connection ID
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a struct clk corresponding to the clock producer, or
   valid <function>IS_ERR</function> condition containing errno.  The implementation
   uses <parameter>dev_id</parameter> and <parameter>con_id</parameter> to determine the clock consumer, and
   thereby the clock producer. In contrast to <function>clk_get</function> this function
   takes the device name instead of the device itself for identification.
   </para><para>

   Drivers must assume that the clock source is not enabled.
   </para><para>

   clk_get_sys should not be called from within interrupt context.
</para>
</refsect1>
</refentry>

<refentry id="API-clk-add-alias">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clk_add_alias</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.1.27</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>clk_add_alias</refname>
 <refpurpose>
     add a new clock alias
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>clk_add_alias </function></funcdef>
   <paramdef>const char * <parameter>alias</parameter></paramdef>
   <paramdef>const char * <parameter>alias_dev_name</parameter></paramdef>
   <paramdef>char * <parameter>id</parameter></paramdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>alias</parameter></term>
   <listitem>
    <para>
     name for clock alias
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alias_dev_name</parameter></term>
   <listitem>
    <para>
     device name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     platform specific clock name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allows using generic clock names for drivers by adding a new alias.
   Assumes clkdev, see clkdev.h for more info.
</para>
</refsect1>
</refentry>

  </chapter>

</book>