<?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="Basics">
     <title>Driver Basics</title>
     <sect1><title>Driver Entry and Exit points</title>
<!-- include/linux/init.h -->
<refentry id="API-module-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>module_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>module_init</refname>
 <refpurpose>
  driver initialization entry point
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>module_init </function></funcdef>
   <paramdef> <parameter>x</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     function to be run at kernel boot time or module insertion
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>module_init</function> will either be called during <function>do_initcalls</function> (if
   builtin) or at module insertion time (if a module).  There can only
   be one per module.
</para>
</refsect1>
</refentry>

<refentry id="API-module-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>module_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>module_exit</refname>
 <refpurpose>
     driver exit entry point
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>module_exit </function></funcdef>
   <paramdef> <parameter>x</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     function to be run when driver is removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>module_exit</function> will wrap the driver clean-up code
   with <function>cleanup_module</function> when used with rmmod when
   the driver is a module.  If the driver is statically
   compiled into the kernel, <function>module_exit</function> has no effect.
   There can only be one per module.
</para>
</refsect1>
</refentry>

     </sect1>

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

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

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

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

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

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

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

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

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

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

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

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

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

<!-- include/asm-i386/unaligned.h -->
<refentry id="API-get-unaligned">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_unaligned</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_unaligned</refname>
 <refpurpose>
  get value from possibly mis-aligned location
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>get_unaligned </function></funcdef>
   <paramdef> <parameter>ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer to value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro should be used for accessing values larger in size than 
   single bytes at locations that are expected to be improperly aligned, 
   e.g. retrieving a u16 value from a location not u16-aligned.
   </para><para>

   Note that unaligned accesses can be very expensive on some architectures.
</para>
</refsect1>
</refentry>

<refentry id="API-put-unaligned">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>put_unaligned</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>put_unaligned</refname>
 <refpurpose>
     put value to a possibly mis-aligned location
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>put_unaligned </function></funcdef>
   <paramdef> <parameter>val</parameter></paramdef>
   <paramdef> <parameter>ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     value to place
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer to location
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro should be used for placing values larger in size than 
   single bytes at locations that are expected to be improperly aligned, 
   e.g. writing a u16 value to a location not u16-aligned.
   </para><para>

   Note that unaligned accesses can be very expensive on some architectures.
</para>
</refsect1>
</refentry>

     </sect1>

     <sect1><title>Delaying, scheduling, and timer routines</title>
<!-- include/linux/sched.h -->
<refentry id="API-pid-alive">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pid_alive</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pid_alive</refname>
 <refpurpose>
  check that a task structure is not stale
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pid_alive </function></funcdef>
   <paramdef>struct task_struct * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     Task structure to be checked.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Test if a process is not yet dead (at most zombie state)
   If pid_alive fails, then pointers within the task structure
   can be stale and must not be dereferenced.
</para>
</refsect1>
</refentry>

<refentry id="API-is-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>is_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>is_init</refname>
 <refpurpose>
     check if a task structure is init
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>is_init </function></funcdef>
   <paramdef>struct task_struct * <parameter>tsk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>tsk</parameter></term>
   <listitem>
    <para>
     Task structure to be checked.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check if a task structure is the first user space task the kernel created.
</para>
</refsect1>
</refentry>

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

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

<refentry id="API---wake-up">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__wake_up</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__wake_up</refname>
 <refpurpose>
     wake up threads blocked on a waitqueue.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void fastcall <function>__wake_up </function></funcdef>
   <paramdef>wait_queue_head_t * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>mode</parameter></paramdef>
   <paramdef>int <parameter>nr_exclusive</parameter></paramdef>
   <paramdef>void * <parameter>key</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the waitqueue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     which threads
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_exclusive</parameter></term>
   <listitem>
    <para>
     how many wake-one or wake-many threads to wake up
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>key</parameter></term>
   <listitem>
    <para>
     is directly passed to the wakeup function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

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

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

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

<refentry id="API-sched-setscheduler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sched_setscheduler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sched_setscheduler</refname>
 <refpurpose>
     change the scheduling policy and/or RT priority of a thread.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sched_setscheduler </function></funcdef>
   <paramdef>struct task_struct * <parameter>p</parameter></paramdef>
   <paramdef>int <parameter>policy</parameter></paramdef>
   <paramdef>struct sched_param * <parameter>param</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     the task in question.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>policy</parameter></term>
   <listitem>
    <para>
     new policy.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>param</parameter></term>
   <listitem>
    <para>
     structure containing the new RT priority.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   NOTE that the task may be already dead.
</para>
</refsect1>
</refentry>

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

   This is a shortcut for kernel-space yielding - it marks the
   thread runnable and calls <function>sys_sched_yield</function>.
</para>
</refsect1>
</refentry>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<refentry id="API-init-timer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>init_timer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>init_timer</refname>
 <refpurpose>
     initialize a timer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void fastcall <function>init_timer </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be initialized
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>init_timer</function> must be done to a timer prior calling *any* of the
   other timer functions.
</para>
</refsect1>
</refentry>

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

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

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

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

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

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

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

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

   It must not be called from interrupt contexts.
</para>
</refsect1>
</refentry>

<refentry id="API-del-timer-sync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>del_timer_sync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>del_timer_sync</refname>
 <refpurpose>
     deactivate a timer and wait for the handler to finish.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>del_timer_sync </function></funcdef>
   <paramdef>struct timer_list * <parameter>timer</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be deactivated
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function only differs from <function>del_timer</function> on SMP: besides deactivating
   the timer it also makes sure the handler has finished executing on other
   CPUs.
</para>
</refsect1>
<refsect1>
<title>Synchronization rules</title>
<para>
   Callers must prevent restarting of the timer,
   otherwise this function is meaningless. It must not be called from
   interrupt contexts. The caller must not hold locks which would prevent
   completion of the timer's handler. The timer's handler must not call
   <function>add_timer_on</function>. Upon exit the timer is not queued and the handler is
   not running on any CPU.
   </para><para>

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

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

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

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

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

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

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

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

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

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

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

<refentry id="API-ktime-sub">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_sub</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_sub</refname>
 <refpurpose>
     subtract two ktime_t variables
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ktime_t <function>ktime_sub </function></funcdef>
   <paramdef>const ktime_t <parameter>lhs</parameter></paramdef>
   <paramdef>const ktime_t <parameter>rhs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>lhs</parameter></term>
   <listitem>
    <para>
     minuend
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rhs</parameter></term>
   <listitem>
    <para>
     subtrahend
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the remainder of the substraction
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_add</refname>
 <refpurpose>
     add two ktime_t variables
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ktime_t <function>ktime_add </function></funcdef>
   <paramdef>const ktime_t <parameter>add1</parameter></paramdef>
   <paramdef>const ktime_t <parameter>add2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>add1</parameter></term>
   <listitem>
    <para>
     addend1
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>add2</parameter></term>
   <listitem>
    <para>
     addend2
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the sum of <parameter>add1</parameter> and <parameter>add2</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-timespec-to-ktime">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>timespec_to_ktime</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>timespec_to_ktime</refname>
 <refpurpose>
     convert a timespec to ktime_t format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ktime_t <function>timespec_to_ktime </function></funcdef>
   <paramdef>const struct timespec <parameter>ts</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ts</parameter></term>
   <listitem>
    <para>
     the timespec variable to convert
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a ktime_t variable with the converted timespec value
</para>
</refsect1>
</refentry>

<refentry id="API-timeval-to-ktime">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>timeval_to_ktime</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>timeval_to_ktime</refname>
 <refpurpose>
     convert a timeval to ktime_t format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ktime_t <function>timeval_to_ktime </function></funcdef>
   <paramdef>const struct timeval <parameter>tv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>tv</parameter></term>
   <listitem>
    <para>
     the timeval variable to convert
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a ktime_t variable with the converted timeval value
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-to-timespec">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_to_timespec</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_to_timespec</refname>
 <refpurpose>
     convert a ktime_t variable to timespec format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct timespec <function>ktime_to_timespec </function></funcdef>
   <paramdef>const ktime_t <parameter>kt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kt</parameter></term>
   <listitem>
    <para>
     the ktime_t variable to convert
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the timespec representation of the ktime value
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-to-timeval">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_to_timeval</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_to_timeval</refname>
 <refpurpose>
     convert a ktime_t variable to timeval format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct timeval <function>ktime_to_timeval </function></funcdef>
   <paramdef>const ktime_t <parameter>kt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kt</parameter></term>
   <listitem>
    <para>
     the ktime_t variable to convert
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the timeval representation of the ktime value
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-to-ns">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_to_ns</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_to_ns</refname>
 <refpurpose>
     convert a ktime_t variable to scalar nanoseconds
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>s64 <function>ktime_to_ns </function></funcdef>
   <paramdef>const ktime_t <parameter>kt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kt</parameter></term>
   <listitem>
    <para>
     the ktime_t variable to convert
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the scalar nanoseconds representation of <parameter>kt</parameter>
</para>
</refsect1>
</refentry>

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

<!-- include/linux/hrtimer.h -->
<refentry id="API-struct-hrtimer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hrtimer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hrtimer</refname>
 <refpurpose>
  the basic hrtimer structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hrtimer {
  struct rb_node node;
  ktime_t expires;
  enum hrtimer_restart		(* function) (struct hrtimer *);
  struct hrtimer_clock_base * base;
  unsigned long state;
#ifdef CONFIG_HIGH_RES_TIMERS
  enum hrtimer_cb_mode cb_mode;
  struct list_head cb_entry;
#endif
#ifdef CONFIG_TIMER_STATS
  void * start_site;
  char start_comm[16];
  int start_pid;
#endif
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>node</term>
      <listitem><para>
red black tree node for time ordered insertion
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>expires</term>
      <listitem><para>
the absolute expiry time in the hrtimers internal
representation. The time is related to the clock on
which the timer is based.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>function</term>
      <listitem><para>
timer expiry callback function
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>base</term>
      <listitem><para>
pointer to the timer base (per cpu and per clock)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>state</term>
      <listitem><para>
state information (See bit values above)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cb_mode</term>
      <listitem><para>
high resolution timer feature to select the callback execution
mode
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cb_entry</term>
      <listitem><para>
list head to enqueue an expired timer into the callback list
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start_site</term>
      <listitem><para>
timer statistics field to store the site where the timer
was started
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start_comm[16]</term>
      <listitem><para>
timer statistics field to store the name of the process which
started the timer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start_pid</term>
      <listitem><para>
timer statistics field to store the pid of the task which
started the timer
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   The hrtimer structure must be initialized by <function>hrtimer_init</function>
</para>
</refsect1>
</refentry>

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

<refentry id="API-struct-hrtimer-clock-base">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct hrtimer_clock_base</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct hrtimer_clock_base</refname>
 <refpurpose>
     the timer base for a specific clock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct hrtimer_clock_base {
  struct hrtimer_cpu_base * cpu_base;
  clockid_t index;
  struct rb_root active;
  struct rb_node * first;
  ktime_t resolution;
  ktime_t (* get_time) (void);
  ktime_t (* get_softirq_time) (void);
  ktime_t softirq_time;
#ifdef CONFIG_HIGH_RES_TIMERS
  ktime_t offset;
  int (* reprogram) (struct hrtimer *t,struct hrtimer_clock_base *b,ktime_t n);
#endif
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>cpu_base</term>
      <listitem><para>
   per cpu clock base
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>index</term>
      <listitem><para>
   clock type index for per_cpu support when moving a
   timer to a base on another cpu.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>active</term>
      <listitem><para>
   red black tree root node for the active timers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>first</term>
      <listitem><para>
   pointer to the timer node which expires first
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>resolution</term>
      <listitem><para>
   the resolution of the clock, in nanoseconds
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_time</term>
      <listitem><para>
   function to retrieve the current time of the clock
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_softirq_time</term>
      <listitem><para>
   function to retrieve the current time from the softirq
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>softirq_time</term>
      <listitem><para>
   the time when running the hrtimer queue in the softirq
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>offset</term>
      <listitem><para>
   offset of this clock to the monotonic base
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>reprogram</term>
      <listitem><para>
   function to reprogram the timer event
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- kernel/hrtimer.c -->
<refentry id="API-ktime-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_get</refname>
 <refpurpose>
  get the monotonic time in ktime_t format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ktime_t <function>ktime_get </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 the time in ktime_t format
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-get-real">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_get_real</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_get_real</refname>
 <refpurpose>
     get the real (wall-) time in ktime_t format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ktime_t <function>ktime_get_real </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 the time in ktime_t format
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-get-ts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_get_ts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_get_ts</refname>
 <refpurpose>
     get the monotonic clock in timespec format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ktime_get_ts </function></funcdef>
   <paramdef>struct timespec * <parameter>ts</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ts</parameter></term>
   <listitem>
    <para>
     pointer to timespec variable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The function calculates the monotonic clock from the realtime
   clock and the wall_to_monotonic offset and stores the result
   in normalized timespec format in the variable pointed to by <parameter>ts</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-ktime-add-ns">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ktime_add_ns</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ktime_add_ns</refname>
 <refpurpose>
     Add a scalar nanoseconds value to a ktime_t variable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ktime_t <function>ktime_add_ns </function></funcdef>
   <paramdef>const ktime_t <parameter>kt</parameter></paramdef>
   <paramdef>u64 <parameter>nsec</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kt</parameter></term>
   <listitem>
    <para>
     addend
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nsec</parameter></term>
   <listitem>
    <para>
     the scalar nsec value to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the sum of kt and nsec in ktime_t format
</para>
</refsect1>
</refentry>

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

<refentry id="API-hrtimer-start">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hrtimer_start</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hrtimer_start</refname>
 <refpurpose>
     (re)start an relative timer on the current CPU
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hrtimer_start </function></funcdef>
   <paramdef>struct hrtimer * <parameter>timer</parameter></paramdef>
   <paramdef>ktime_t <parameter>tim</parameter></paramdef>
   <paramdef>const enum hrtimer_mode <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tim</parameter></term>
   <listitem>
    <para>
     expiry time
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     expiry mode: absolute (HRTIMER_ABS) or relative (HRTIMER_REL)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success
   1 when the timer was active
</para>
</refsect1>
</refentry>

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

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

<refentry id="API-hrtimer-get-remaining">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hrtimer_get_remaining</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hrtimer_get_remaining</refname>
 <refpurpose>
     get remaining time for the timer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ktime_t <function>hrtimer_get_remaining </function></funcdef>
   <paramdef>const struct hrtimer * <parameter>timer</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>timer</parameter></term>
   <listitem>
    <para>
     the timer to read
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

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

<refentry id="API-hrtimer-get-res">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hrtimer_get_res</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hrtimer_get_res</refname>
 <refpurpose>
     get the timer resolution for a clock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hrtimer_get_res </function></funcdef>
   <paramdef>const clockid_t <parameter>which_clock</parameter></paramdef>
   <paramdef>struct timespec * <parameter>tp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>which_clock</parameter></term>
   <listitem>
    <para>
     which clock to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tp</parameter></term>
   <listitem>
    <para>
     pointer to timespec variable to store the resolution
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Store the resolution of the clock selected by <parameter>which_clock</parameter> in the
   variable pointed to by <parameter>tp</parameter>.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Workqueues and Kevents</title>
<!-- kernel/workqueue.c -->
<refentry id="API-queue-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>queue_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>queue_work</refname>
 <refpurpose>
  queue work on a workqueue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int fastcall <function>queue_work </function></funcdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     work to queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 if <parameter>work</parameter> was already on a queue, non-zero otherwise.
   </para><para>

   We queue the work to the CPU it was submitted, but there is no
   guarantee that it will be processed by that CPU.
</para>
</refsect1>
</refentry>

<refentry id="API-queue-delayed-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>queue_delayed_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>queue_delayed_work</refname>
 <refpurpose>
     queue work on a workqueue after delay
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int fastcall <function>queue_delayed_work </function></funcdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
   <paramdef>unsigned long <parameter>delay</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     delayable work to queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delay</parameter></term>
   <listitem>
    <para>
     number of jiffies to wait before queueing
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 if <parameter>work</parameter> was already on a queue, non-zero otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-queue-delayed-work-on">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>queue_delayed_work_on</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>queue_delayed_work_on</refname>
 <refpurpose>
     queue work on specific CPU after delay
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>queue_delayed_work_on </function></funcdef>
   <paramdef>int <parameter>cpu</parameter></paramdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
   <paramdef>unsigned long <parameter>delay</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cpu</parameter></term>
   <listitem>
    <para>
     CPU number to execute work on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     work to queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delay</parameter></term>
   <listitem>
    <para>
     number of jiffies to wait before queueing
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 if <parameter>work</parameter> was already on a queue, non-zero otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-flush-workqueue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>flush_workqueue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>flush_workqueue</refname>
 <refpurpose>
     ensure that any scheduled work has run to completion.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void fastcall <function>flush_workqueue </function></funcdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     workqueue to flush
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Forces execution of the workqueue and blocks until its completion.
   This is typically used in driver shutdown handlers.
   </para><para>

   We sleep until all works which were queued on entry have been handled,
   but we are not livelocked by new incoming ones.
   </para><para>

   This function used to run the workqueues itself.  Now we just wait for the
   helper threads to do it.
</para>
</refsect1>
</refentry>

<refentry id="API-cancel-work-sync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cancel_work_sync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cancel_work_sync</refname>
 <refpurpose>
     block until a work_struct's callback has terminated
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>cancel_work_sync </function></funcdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     the work which is to be flushed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if <parameter>work</parameter> was pending.
   </para><para>

   <function>cancel_work_sync</function> will cancel the work if it is queued. If the work's
   callback appears to be running, <function>cancel_work_sync</function> will block until it
   has completed.
   </para><para>

   It is possible to use this function if the work re-queues itself. It can
   cancel the work even if it migrates to another workqueue, however in that
   case it only guarantees that work-&gt;<function>func</function> has completed on the last queued
   workqueue.
   </para><para>

   cancel_work_sync(&amp;delayed_work-&gt;work) should be used only if -&gt;timer is not
   pending, otherwise it goes into a busy-wait loop until the timer expires.
   </para><para>

   The caller must ensure that workqueue_struct on which this work was last
   queued can't be destroyed before this function returns.
</para>
</refsect1>
</refentry>

<refentry id="API-cancel-delayed-work-sync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cancel_delayed_work_sync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>cancel_delayed_work_sync</refname>
 <refpurpose>
     reliably kill off a delayed work.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>cancel_delayed_work_sync </function></funcdef>
   <paramdef>struct delayed_work * <parameter>dwork</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dwork</parameter></term>
   <listitem>
    <para>
     the delayed work struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if <parameter>dwork</parameter> was pending.
   </para><para>

   It is possible to use this function if <parameter>dwork</parameter> rearms itself via <function>queue_work</function>
   or <function>queue_delayed_work</function>. See also the comment for <function>cancel_work_sync</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-schedule-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>schedule_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>schedule_work</refname>
 <refpurpose>
     put work task in global workqueue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int fastcall <function>schedule_work </function></funcdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     job to be done
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This puts a job in the kernel-global workqueue.
</para>
</refsect1>
</refentry>

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

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

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

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

     </sect1>
     <sect1><title>Internal Functions</title>
<!-- kernel/exit.c -->
<refentry id="API-reparent-to-kthreadd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>reparent_to_kthreadd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>reparent_to_kthreadd</refname>
 <refpurpose>
  Reparent the calling kernel thread to kthreadd
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>reparent_to_kthreadd </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   If a kernel thread is launched as a result of a system call, or if
   it ever exits, it should generally reparent itself to kthreadd so it
   isn't in the way of other processes and is correctly cleaned up on exit.
   </para><para>

   The various task state such as scheduling policy and priority may have
   been inherited from a user process, so we reset them to sane values here.
   </para><para>

   NOTE that <function>reparent_to_kthreadd</function> gives the caller full capabilities.
</para>
</refsect1>
</refentry>

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

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

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

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

<refentry id="API-kthread-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_create</refname>
 <refpurpose>
     create a kthread.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct task_struct * <function>kthread_create </function></funcdef>
   <paramdef>int (*<parameter>threadfn</parameter>)
     <funcparams>void *data</funcparams></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>const char <parameter>namefmt[]</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>threadfn</parameter></term>
   <listitem>
    <para>
     the function to run until signal_pending(current).
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data ptr for <parameter>threadfn</parameter>.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>namefmt[]</parameter></term>
   <listitem>
    <para>
     printf-style name for the thread.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This helper function creates and names a kernel
   thread.  The thread will be stopped: use <function>wake_up_process</function> to start
   it.  See also <function>kthread_run</function>, <function>kthread_create_on_cpu</function>.
   </para><para>

   When woken, the thread will run <parameter>threadfn</parameter>() with <parameter>data</parameter> as its
   argument. <parameter>threadfn</parameter>() can either call <function>do_exit</function> directly if it is a
   standalone thread for which noone will call <function>kthread_stop</function>, or
   return when '<function>kthread_should_stop</function>' is true (which means
   <function>kthread_stop</function> has been called).  The return value should be zero
   or a negative error number; it will be passed to <function>kthread_stop</function>.
   </para><para>

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

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

<refentry id="API-kthread-stop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kthread_stop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kthread_stop</refname>
 <refpurpose>
     stop a thread created by <function>kthread_create</function>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kthread_stop </function></funcdef>
   <paramdef>struct task_struct * <parameter>k</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>k</parameter></term>
   <listitem>
    <para>
     thread created by <function>kthread_create</function>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets <function>kthread_should_stop</function> for <parameter>k</parameter> to return true, wakes it, and
   waits for it to exit.  Your <function>threadfn</function> must not call <function>do_exit</function>
   itself if you use this function!  This can also be called after
   <function>kthread_create</function> instead of calling <function>wake_up_process</function>: the thread
   will exit without calling <function>threadfn</function>.
   </para><para>

   Returns the result of <function>threadfn</function>, or <constant>-EINTR</constant> if <function>wake_up_process</function>
   was never called.
</para>
</refsect1>
</refentry>

     </sect1>

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

<refentry id="API-kobject-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_init</refname>
 <refpurpose>
     initialize object.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kobject_init </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     object in question.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kobject-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_add</refname>
 <refpurpose>
     add an object to the hierarchy.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kobject_add </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     object.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kobject-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_register</refname>
 <refpurpose>
     initialize and add an object.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kobject_register </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     object in question.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kobject-set-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_set_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_set_name</refname>
 <refpurpose>
     Set the name of an object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kobject_set_name </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     object.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string used to build the name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If strlen(name) &gt;= KOBJ_NAME_LEN, then use a dynamically allocated
   string that <parameter>kobj</parameter>-&gt;k_name points to. Otherwise, use the static 
   <parameter>kobj</parameter>-&gt;name array.
</para>
</refsect1>
</refentry>

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

<refentry id="API-kobject-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kobject_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kobject_unregister</refname>
 <refpurpose>
     remove object from hierarchy and decrement refcount.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kobject_unregister </function></funcdef>
   <paramdef>struct kobject * <parameter>kobj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kobj</parameter></term>
   <listitem>
    <para>
     object going away.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

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

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

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

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

<refentry id="API-subsys-create-file">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>subsys_create_file</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>subsys_create_file</refname>
 <refpurpose>
     export sysfs attribute file.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>subsys_create_file </function></funcdef>
   <paramdef>struct kset * <parameter>s</parameter></paramdef>
   <paramdef>struct subsys_attribute * <parameter>a</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     subsystem.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>a</parameter></term>
   <listitem>
    <para>
     subsystem attribute descriptor.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>

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

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

<!-- kernel/printk.c -->
<refentry id="API-printk">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>printk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>printk</refname>
 <refpurpose>
  print a kernel message
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>printk </function></funcdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is <function>printk</function>.  It can be called from any context.  We want it to work.
   Be aware of the fact that if oops_in_progress is not set, we might try to
   wake klogd up which could deadlock on runqueue lock if <function>printk</function> is called
   from scheduler code.
   </para><para>

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

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

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

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

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

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

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

   While the semaphore was held, console output may have been buffered
   by <function>printk</function>.  If this is the case, <function>release_console_sem</function> emits
   the output prior to releasing the semaphore.
   </para><para>

   If there is output waiting for klogd, we wake it up.
   </para><para>

   <function>release_console_sem</function> may be called from any context.
</para>
</refsect1>
</refentry>

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

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

   Must be called within <function>acquire_console_sem</function>.
</para>
</refsect1>
</refentry>

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

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

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

<!-- kernel/sys.c -->
<refentry id="API-atomic-notifier-chain-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_notifier_chain_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_notifier_chain_register</refname>
 <refpurpose>
  Add notifier to an atomic notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>atomic_notifier_chain_register </function></funcdef>
   <paramdef>struct atomic_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>struct notifier_block * <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the atomic notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     New entry in notifier chain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds a notifier to an atomic notifier chain.
   </para><para>

   Currently always returns zero.
</para>
</refsect1>
</refentry>

<refentry id="API-atomic-notifier-chain-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>atomic_notifier_chain_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>atomic_notifier_chain_unregister</refname>
 <refpurpose>
     Remove notifier from an atomic notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>atomic_notifier_chain_unregister </function></funcdef>
   <paramdef>struct atomic_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>struct notifier_block * <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the atomic notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     Entry to remove from notifier chain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes a notifier from an atomic notifier chain.
   </para><para>

   Returns zero on success or <constant>-ENOENT</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API---atomic-notifier-call-chain">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__atomic_notifier_call_chain</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__atomic_notifier_call_chain</refname>
 <refpurpose>
     Call functions in an atomic notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __kprobes <function>__atomic_notifier_call_chain </function></funcdef>
   <paramdef>struct atomic_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>unsigned long <parameter>val</parameter></paramdef>
   <paramdef>void * <parameter>v</parameter></paramdef>
   <paramdef>int <parameter>nr_to_call</parameter></paramdef>
   <paramdef>int * <parameter>nr_calls</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the atomic notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     Value passed unmodified to notifier function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     Pointer passed unmodified to notifier function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_to_call</parameter></term>
   <listitem>
    <para>
     See the comment for notifier_call_chain.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_calls</parameter></term>
   <listitem>
    <para>
     See the comment for notifier_call_chain.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls each function in a notifier chain in turn.  The functions
   run in an atomic context, so they must not block.
   This routine uses RCU to synchronize with changes to the chain.
   </para><para>

   If the return value of the notifier can be and'ed
   with <constant>NOTIFY_STOP_MASK</constant> then <function>atomic_notifier_call_chain</function>
   will return immediately, with the return value of
   the notifier function which halted execution.
   Otherwise the return value is the return value
   of the last notifier function called.
</para>
</refsect1>
</refentry>

<refentry id="API-blocking-notifier-chain-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blocking_notifier_chain_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blocking_notifier_chain_register</refname>
 <refpurpose>
     Add notifier to a blocking notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blocking_notifier_chain_register </function></funcdef>
   <paramdef>struct blocking_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>struct notifier_block * <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the blocking notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     New entry in notifier chain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds a notifier to a blocking notifier chain.
   Must be called in process context.
   </para><para>

   Currently always returns zero.
</para>
</refsect1>
</refentry>

<refentry id="API-blocking-notifier-chain-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blocking_notifier_chain_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blocking_notifier_chain_unregister</refname>
 <refpurpose>
     Remove notifier from a blocking notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blocking_notifier_chain_unregister </function></funcdef>
   <paramdef>struct blocking_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>struct notifier_block * <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the blocking notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     Entry to remove from notifier chain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes a notifier from a blocking notifier chain.
   Must be called from process context.
   </para><para>

   Returns zero on success or <constant>-ENOENT</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API---blocking-notifier-call-chain">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__blocking_notifier_call_chain</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__blocking_notifier_call_chain</refname>
 <refpurpose>
     Call functions in a blocking notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__blocking_notifier_call_chain </function></funcdef>
   <paramdef>struct blocking_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>unsigned long <parameter>val</parameter></paramdef>
   <paramdef>void * <parameter>v</parameter></paramdef>
   <paramdef>int <parameter>nr_to_call</parameter></paramdef>
   <paramdef>int * <parameter>nr_calls</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the blocking notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     Value passed unmodified to notifier function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     Pointer passed unmodified to notifier function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_to_call</parameter></term>
   <listitem>
    <para>
     See comment for notifier_call_chain.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_calls</parameter></term>
   <listitem>
    <para>
     See comment for notifier_call_chain.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls each function in a notifier chain in turn.  The functions
   run in a process context, so they are allowed to block.
   </para><para>

   If the return value of the notifier can be and'ed
   with <constant>NOTIFY_STOP_MASK</constant> then <function>blocking_notifier_call_chain</function>
   will return immediately, with the return value of
   the notifier function which halted execution.
   Otherwise the return value is the return value
   of the last notifier function called.
</para>
</refsect1>
</refentry>

<refentry id="API-raw-notifier-chain-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>raw_notifier_chain_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>raw_notifier_chain_register</refname>
 <refpurpose>
     Add notifier to a raw notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>raw_notifier_chain_register </function></funcdef>
   <paramdef>struct raw_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>struct notifier_block * <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the raw notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     New entry in notifier chain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds a notifier to a raw notifier chain.
   All locking must be provided by the caller.
   </para><para>

   Currently always returns zero.
</para>
</refsect1>
</refentry>

<refentry id="API-raw-notifier-chain-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>raw_notifier_chain_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>raw_notifier_chain_unregister</refname>
 <refpurpose>
     Remove notifier from a raw notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>raw_notifier_chain_unregister </function></funcdef>
   <paramdef>struct raw_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>struct notifier_block * <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the raw notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     Entry to remove from notifier chain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes a notifier from a raw notifier chain.
   All locking must be provided by the caller.
   </para><para>

   Returns zero on success or <constant>-ENOENT</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API---raw-notifier-call-chain">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__raw_notifier_call_chain</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__raw_notifier_call_chain</refname>
 <refpurpose>
     Call functions in a raw notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__raw_notifier_call_chain </function></funcdef>
   <paramdef>struct raw_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>unsigned long <parameter>val</parameter></paramdef>
   <paramdef>void * <parameter>v</parameter></paramdef>
   <paramdef>int <parameter>nr_to_call</parameter></paramdef>
   <paramdef>int * <parameter>nr_calls</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the raw notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     Value passed unmodified to notifier function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     Pointer passed unmodified to notifier function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_to_call</parameter></term>
   <listitem>
    <para>
     See comment for notifier_call_chain.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_calls</parameter></term>
   <listitem>
    <para>
     See comment for notifier_call_chain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls each function in a notifier chain in turn.  The functions
   run in an undefined context.
   All locking must be provided by the caller.
   </para><para>

   If the return value of the notifier can be and'ed
   with <constant>NOTIFY_STOP_MASK</constant> then <function>raw_notifier_call_chain</function>
   will return immediately, with the return value of
   the notifier function which halted execution.
   Otherwise the return value is the return value
   of the last notifier function called.
</para>
</refsect1>
</refentry>

<refentry id="API-srcu-notifier-chain-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>srcu_notifier_chain_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>srcu_notifier_chain_register</refname>
 <refpurpose>
     Add notifier to an SRCU notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>srcu_notifier_chain_register </function></funcdef>
   <paramdef>struct srcu_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>struct notifier_block * <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the SRCU notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     New entry in notifier chain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds a notifier to an SRCU notifier chain.
   Must be called in process context.
   </para><para>

   Currently always returns zero.
</para>
</refsect1>
</refentry>

<refentry id="API-srcu-notifier-chain-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>srcu_notifier_chain_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>srcu_notifier_chain_unregister</refname>
 <refpurpose>
     Remove notifier from an SRCU notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>srcu_notifier_chain_unregister </function></funcdef>
   <paramdef>struct srcu_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>struct notifier_block * <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the SRCU notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     Entry to remove from notifier chain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes a notifier from an SRCU notifier chain.
   Must be called from process context.
   </para><para>

   Returns zero on success or <constant>-ENOENT</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API---srcu-notifier-call-chain">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__srcu_notifier_call_chain</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__srcu_notifier_call_chain</refname>
 <refpurpose>
     Call functions in an SRCU notifier chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__srcu_notifier_call_chain </function></funcdef>
   <paramdef>struct srcu_notifier_head * <parameter>nh</parameter></paramdef>
   <paramdef>unsigned long <parameter>val</parameter></paramdef>
   <paramdef>void * <parameter>v</parameter></paramdef>
   <paramdef>int <parameter>nr_to_call</parameter></paramdef>
   <paramdef>int * <parameter>nr_calls</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the SRCU notifier chain
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     Value passed unmodified to notifier function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     Pointer passed unmodified to notifier function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_to_call</parameter></term>
   <listitem>
    <para>
     See comment for notifier_call_chain.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_calls</parameter></term>
   <listitem>
    <para>
     See comment for notifier_call_chain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls each function in a notifier chain in turn.  The functions
   run in a process context, so they are allowed to block.
   </para><para>

   If the return value of the notifier can be and'ed
   with <constant>NOTIFY_STOP_MASK</constant> then <function>srcu_notifier_call_chain</function>
   will return immediately, with the return value of
   the notifier function which halted execution.
   Otherwise the return value is the return value
   of the last notifier function called.
</para>
</refsect1>
</refentry>

<refentry id="API-srcu-init-notifier-head">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>srcu_init_notifier_head</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>srcu_init_notifier_head</refname>
 <refpurpose>
     Initialize an SRCU notifier head
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>srcu_init_notifier_head </function></funcdef>
   <paramdef>struct srcu_notifier_head * <parameter>nh</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nh</parameter></term>
   <listitem>
    <para>
     Pointer to head of the srcu notifier chain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unlike other sorts of notifier heads, SRCU notifier heads require
   dynamic initialization.  Be sure to call this routine before
   calling any of the other SRCU notifier routines for this head.
   </para><para>

   If an SRCU notifier head is deallocated, it must first be cleaned
   up by calling <function>srcu_cleanup_notifier_head</function>.  Otherwise the head's
   per-cpu data (used by the SRCU mechanism) will leak.
</para>
</refsect1>
</refentry>

<refentry id="API-register-reboot-notifier">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_reboot_notifier</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_reboot_notifier</refname>
 <refpurpose>
     Register function to be called at reboot time
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_reboot_notifier </function></funcdef>
   <paramdef>struct notifier_block * <parameter>nb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nb</parameter></term>
   <listitem>
    <para>
     Info about notifier function to be called
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers a function with the list of functions
   to be called at reboot time.
   </para><para>

   Currently always returns zero, as <function>blocking_notifier_chain_register</function>
   always returns zero.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-reboot-notifier">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_reboot_notifier</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_reboot_notifier</refname>
 <refpurpose>
     Unregister previously registered reboot notifier
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>unregister_reboot_notifier </function></funcdef>
   <paramdef>struct notifier_block * <parameter>nb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nb</parameter></term>
   <listitem>
    <para>
     Hook to be unregistered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregisters a previously registered reboot
   notifier function.
   </para><para>

   Returns zero on success, or <constant>-ENOENT</constant> on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-emergency-restart">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>emergency_restart</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>emergency_restart</refname>
 <refpurpose>
     reboot the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>emergency_restart </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>

   Without shutting down any hardware or taking any locks
   reboot the system.  This is called when we know we are in
   trouble so this is our best effort to reboot.  This is
   safe to call in interrupt context.
</para>
</refsect1>
</refentry>

<refentry id="API-kernel-restart">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kernel_restart</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kernel_restart</refname>
 <refpurpose>
     reboot the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kernel_restart </function></funcdef>
   <paramdef>char * <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     pointer to buffer containing command to execute for restart
     or <constant>NULL</constant>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Shutdown everything and perform a clean reboot.
   This is not safe to call in interrupt context.
</para>
</refsect1>
</refentry>

<refentry id="API-kernel-halt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kernel_halt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kernel_halt</refname>
 <refpurpose>
     halt the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kernel_halt </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>

   Shutdown everything and perform a clean system halt.
</para>
</refsect1>
</refentry>

<refentry id="API-kernel-power-off">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kernel_power_off</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kernel_power_off</refname>
 <refpurpose>
     power_off the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kernel_power_off </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>

   Shutdown everything and perform a clean system power_off.
</para>
</refsect1>
</refentry>

<refentry id="API-orderly-poweroff">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>orderly_poweroff</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>orderly_poweroff</refname>
 <refpurpose>
     Trigger an orderly system poweroff
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>orderly_poweroff </function></funcdef>
   <paramdef>bool <parameter>force</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>force</parameter></term>
   <listitem>
    <para>
     force poweroff if command execution fails
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This may be called from any context to trigger a system shutdown.
   If the orderly shutdown fails, it will force an immediate shutdown.
</para>
</refsect1>
</refentry>

<!-- kernel/rcupdate.c -->
<refentry id="API-call-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>call_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>call_rcu</refname>
 <refpurpose>
  Queue an RCU callback for invocation after a grace period.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void fastcall <function>call_rcu </function></funcdef>
   <paramdef>struct rcu_head * <parameter>head</parameter></paramdef>
   <paramdef>void (*<parameter>func</parameter>)
     <funcparams>struct rcu_head *rcu</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     structure to be used for queueing the RCU updates.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>func</parameter></term>
   <listitem>
    <para>
     actual update function to be invoked after the grace period
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The update function will be invoked some time after a full grace
   period elapses, in other words after all currently executing RCU
   read-side critical sections have completed.  RCU read-side critical
   sections are delimited by <function>rcu_read_lock</function> and <function>rcu_read_unlock</function>,
   and may be nested.
</para>
</refsect1>
</refentry>

<refentry id="API-call-rcu-bh">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>call_rcu_bh</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>call_rcu_bh</refname>
 <refpurpose>
     Queue an RCU for invocation after a quicker grace period.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void fastcall <function>call_rcu_bh </function></funcdef>
   <paramdef>struct rcu_head * <parameter>head</parameter></paramdef>
   <paramdef>void (*<parameter>func</parameter>)
     <funcparams>struct rcu_head *rcu</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     structure to be used for queueing the RCU updates.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>func</parameter></term>
   <listitem>
    <para>
     actual update function to be invoked after the grace period
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The update function will be invoked some time after a full grace
   period elapses, in other words after all currently executing RCU
   read-side critical sections have completed. <function>call_rcu_bh</function> assumes
   that the read-side critical sections end on completion of a softirq
   handler. This means that read-side critical sections in process
   context must not be interrupted by softirqs. This interface is to be
   used when most of the read-side critical sections are in softirq context.
   RCU read-side critical sections are delimited by <function>rcu_read_lock</function> and
   <function>rcu_read_unlock</function>, * if in interrupt context or <function>rcu_read_lock_bh</function>
   and <function>rcu_read_unlock_bh</function>, if in process context. These may be nested.
</para>
</refsect1>
</refentry>

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

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

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

   If your read-side code is not protected by <function>rcu_read_lock</function>, do -not-
   use <function>synchronize_rcu</function>.
</para>
</refsect1>
</refentry>

     </sect1>

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

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

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

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

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

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

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

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

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

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

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

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

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

     </sect1>

  </chapter>

  <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_add_tail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-add-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_add_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_add_rcu</refname>
 <refpurpose>
     add a new entry to rcu-protected list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_add_rcu </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><para>

   The caller must take whatever precautions are necessary
   (such as holding appropriate locks) to avoid racing
   with another list-mutation primitive, such as <function>list_add_rcu</function>
   or <function>list_del_rcu</function>, running on this same list.
   However, it is perfectly legal to run concurrently with
   the _rcu list-traversal primitives, such as
   <function>list_for_each_entry_rcu</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-list-add-tail-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_add_tail_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_add_tail_rcu</refname>
 <refpurpose>
     add a new entry to rcu-protected list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_add_tail_rcu </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><para>

   The caller must take whatever precautions are necessary
   (such as holding appropriate locks) to avoid racing
   with another list-mutation primitive, such as <function>list_add_tail_rcu</function>
   or <function>list_del_rcu</function>, running on this same list.
   However, it is perfectly legal to run concurrently with
   the _rcu list-traversal primitives, such as
   <function>list_for_each_entry_rcu</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-list-del">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_del</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_del</refname>
 <refpurpose>
     deletes entry from list.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_del </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-del-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_del_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_del_rcu</refname>
 <refpurpose>
     deletes entry from list without re-initialization
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_del_rcu </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. It is useful for RCU based
   lockfree traversal.
   </para><para>

   In particular, it means that we can not poison the forward
   pointers that may still be used for walking the list.
   </para><para>

   The caller must take whatever precautions are necessary
   (such as holding appropriate locks) to avoid racing
   with another list-mutation primitive, such as <function>list_del_rcu</function>
   or <function>list_add_rcu</function>, running on this same list.
   However, it is perfectly legal to run concurrently with
   the _rcu list-traversal primitives, such as
   <function>list_for_each_entry_rcu</function>.
   </para><para>

   Note that the caller is not permitted to immediately free
   the newly deleted entry.  Instead, either <function>synchronize_rcu</function>
   or <function>call_rcu</function> must be used to defer freeing until an RCU
   grace period has elapsed.
</para>
</refsect1>
</refentry>

<refentry id="API-list-replace">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_replace</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-replace-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_replace_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_replace_rcu</refname>
 <refpurpose>
     replace old entry by new one
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_replace_rcu </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>
   The <parameter>old</parameter> entry will be replaced with the <parameter>new</parameter> entry atomically.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   <parameter>old</parameter> should not be empty.
</para>
</refsect1>
</refentry>

<refentry id="API-list-del-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_del_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_move</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_move_tail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_is_last</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_empty_careful</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-splice">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_splice</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_splice</refname>
 <refpurpose>
     join two lists
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_splice </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_splice_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-init-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_splice_init_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_splice_init_rcu</refname>
 <refpurpose>
     splice an RCU-protected list into an existing list.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>list_splice_init_rcu </function></funcdef>
   <paramdef>struct list_head * <parameter>list</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
   <paramdef>void (*<parameter>sync</parameter>)
     <funcparams>void</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     the RCU-protected list to splice
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     the place in the list to splice the first list into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sync</parameter></term>
   <listitem>
    <para>
     function to sync: <function>synchronize_rcu</function>, <function>synchronize_sched</function>, ...
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <parameter>head</parameter> can be RCU-read traversed concurrently with this function.
   </para><para>

   Note that this function blocks.
</para>
</refsect1>
<refsect1>
<title>Important note</title>
<para>
   the caller must take whatever action is necessary to
   prevent any other updates to <parameter>head</parameter>.  In principle, it is possible
   to modify the list as soon as <function>sync</function> begins execution.
   If this sort of thing becomes necessary, an alternative version
   based on <function>call_rcu</function> could be created.  But only if -really-
   needed -- there is no shortage of RCU API members.
</para>
</refsect1>
</refentry>

<refentry id="API-list-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 &amp;struct list_head 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_struct 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_first_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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_struct 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-for-each">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 &amp;struct list_head 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">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__list_for_each</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 &amp;struct list_head 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>
<refsect1>
<title>Description</title>
<para>
   This variant differs from <function>list_for_each</function> in that it's the
   simplest possible list iteration code, no prefetching is done.
   Use this for code that knows the list to be very short (empty
   or 1 entry) most of the time.
</para>
</refsect1>
</refentry>

<refentry id="API-list-for-each-prev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_prev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 &amp;struct list_head 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_safe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 &amp;struct list_head to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     another &amp;struct list_head 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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_struct 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_reverse</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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_struct 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_prepare_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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_struct 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_continue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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_struct 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-from">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_from</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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_struct 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_safe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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_struct 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_safe_continue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_safe_continue</refname>
 <refpurpose>
   </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_struct 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_safe_from</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_safe_from</refname>
 <refpurpose>
   </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_struct 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_safe_reverse</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_safe_reverse</refname>
 <refpurpose>
   </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_struct 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-for-each-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_rcu</refname>
 <refpurpose>
     iterate over an rcu-protected list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_rcu </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 &amp;struct list_head 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>
<refsect1>
<title>Description</title>
<para>
   This list-traversal primitive may safely run concurrently with
   the _rcu list-mutation primitives such as <function>list_add_rcu</function>
   as long as the traversal is guarded by <function>rcu_read_lock</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-list-for-each-safe-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_safe_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_safe_rcu</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_safe_rcu </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 &amp;struct list_head to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     another &amp;struct list_head 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>
<refsect1>
<title>Description</title>
<para>
   Iterate over an rcu-protected list, safe against removal of list entry.
   </para><para>

   This list-traversal primitive may safely run concurrently with
   the _rcu list-mutation primitives such as <function>list_add_rcu</function>
   as long as the traversal is guarded by <function>rcu_read_lock</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-list-for-each-entry-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_entry_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_entry_rcu</refname>
 <refpurpose>
     iterate over rcu list of given type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_entry_rcu </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_struct within the struct.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This list-traversal primitive may safely run concurrently with
   the _rcu list-mutation primitives such as <function>list_add_rcu</function>
   as long as the traversal is guarded by <function>rcu_read_lock</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-list-for-each-continue-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>list_for_each_continue_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>list_for_each_continue_rcu</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>list_for_each_continue_rcu </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 &amp;struct list_head 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>
<refsect1>
<title>Description</title>
<para>
   Iterate over an rcu-protected list, continuing after current point.
   </para><para>

   This list-traversal primitive may safely run concurrently with
   the _rcu list-mutation primitives such as <function>list_add_rcu</function>
   as long as the traversal is guarded by <function>rcu_read_lock</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-hlist-del-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_del_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hlist_del_rcu</refname>
 <refpurpose>
     deletes entry from hash list without re-initialization
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hlist_del_rcu </function></funcdef>
   <paramdef>struct hlist_node * <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     the element to delete from the hash list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   <function>list_unhashed</function> on entry does not return true after this,
   the entry is in an undefined state. It is useful for RCU based
   lockfree traversal.
   </para><para>

   In particular, it means that we can not poison the forward
   pointers that may still be used for walking the hash list.
   </para><para>

   The caller must take whatever precautions are necessary
   (such as holding appropriate locks) to avoid racing
   with another list-mutation primitive, such as <function>hlist_add_head_rcu</function>
   or <function>hlist_del_rcu</function>, running on this same list.
   However, it is perfectly legal to run concurrently with
   the _rcu list-traversal primitives, such as
   <function>hlist_for_each_entry</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-hlist-replace-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_replace_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hlist_replace_rcu</refname>
 <refpurpose>
     replace old entry by new one
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hlist_replace_rcu </function></funcdef>
   <paramdef>struct hlist_node * <parameter>old</parameter></paramdef>
   <paramdef>struct hlist_node * <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>
   The <parameter>old</parameter> entry will be replaced with the <parameter>new</parameter> entry atomically.
</para>
</refsect1>
</refentry>

<refentry id="API-hlist-add-head-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_add_head_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hlist_add_head_rcu</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hlist_add_head_rcu </function></funcdef>
   <paramdef>struct hlist_node * <parameter>n</parameter></paramdef>
   <paramdef>struct hlist_head * <parameter>h</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     the element to add to the hash list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>h</parameter></term>
   <listitem>
    <para>
     the list to add to.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds the specified element to the specified hlist,
   while permitting racing traversals.
   </para><para>

   The caller must take whatever precautions are necessary
   (such as holding appropriate locks) to avoid racing
   with another list-mutation primitive, such as <function>hlist_add_head_rcu</function>
   or <function>hlist_del_rcu</function>, running on this same list.
   However, it is perfectly legal to run concurrently with
   the _rcu list-traversal primitives, such as
   <function>hlist_for_each_entry_rcu</function>, used to prevent memory-consistency
   problems on Alpha CPUs.  Regardless of the type of CPU, the
   list-traversal primitive must be guarded by <function>rcu_read_lock</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-hlist-add-before-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_add_before_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hlist_add_before_rcu</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hlist_add_before_rcu </function></funcdef>
   <paramdef>struct hlist_node * <parameter>n</parameter></paramdef>
   <paramdef>struct hlist_node * <parameter>next</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     the new element to add to the hash list.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>next</parameter></term>
   <listitem>
    <para>
     the existing element to add the new element before.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds the specified element to the specified hlist
   before the specified node while permitting racing traversals.
   </para><para>

   The caller must take whatever precautions are necessary
   (such as holding appropriate locks) to avoid racing
   with another list-mutation primitive, such as <function>hlist_add_head_rcu</function>
   or <function>hlist_del_rcu</function>, running on this same list.
   However, it is perfectly legal to run concurrently with
   the _rcu list-traversal primitives, such as
   <function>hlist_for_each_entry_rcu</function>, used to prevent memory-consistency
   problems on Alpha CPUs.
</para>
</refsect1>
</refentry>

<refentry id="API-hlist-add-after-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_add_after_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hlist_add_after_rcu</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hlist_add_after_rcu </function></funcdef>
   <paramdef>struct hlist_node * <parameter>prev</parameter></paramdef>
   <paramdef>struct hlist_node * <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>prev</parameter></term>
   <listitem>
    <para>
     the existing element to add the new element after.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     the new element to add to the hash list.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds the specified element to the specified hlist
   after the specified node while permitting racing traversals.
   </para><para>

   The caller must take whatever precautions are necessary
   (such as holding appropriate locks) to avoid racing
   with another list-mutation primitive, such as <function>hlist_add_head_rcu</function>
   or <function>hlist_del_rcu</function>, running on this same list.
   However, it is perfectly legal to run concurrently with
   the _rcu list-traversal primitives, such as
   <function>hlist_for_each_entry_rcu</function>, used to prevent memory-consistency
   problems on Alpha CPUs.
</para>
</refsect1>
</refentry>

<refentry id="API-hlist-for-each-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_for_each_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>tpos</parameter></paramdef>
   <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>tpos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the &amp;struct hlist_node 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_for_each_entry_continue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>tpos</parameter></paramdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>tpos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the &amp;struct hlist_node 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_for_each_entry_from</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>tpos</parameter></paramdef>
   <paramdef> <parameter>pos</parameter></paramdef>
   <paramdef> <parameter>member</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>tpos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the &amp;struct hlist_node 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_for_each_entry_safe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>tpos</parameter></paramdef>
   <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>tpos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the &amp;struct hlist_node to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     another &amp;struct hlist_node 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>

<refentry id="API-hlist-for-each-entry-rcu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hlist_for_each_entry_rcu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hlist_for_each_entry_rcu</refname>
 <refpurpose>
     iterate over rcu list of given type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>hlist_for_each_entry_rcu </function></funcdef>
   <paramdef> <parameter>tpos</parameter></paramdef>
   <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>tpos</parameter></term>
   <listitem>
    <para>
     the type * to use as a loop cursor.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     the &amp;struct hlist_node 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>
<refsect1>
<title>Description</title>
<para>
   This list-traversal primitive may safely run concurrently with
   the _rcu list-mutation primitives such as <function>hlist_add_head_rcu</function>
   as long as the traversal is guarded by <function>rcu_read_lock</function>.
</para>
</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-strtoll">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>simple_strtoll</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refentry>

<!-- lib/vsprintf.c -->
<refentry id="API-simple-strtoul">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>simple_strtoul</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refentry>

<refentry id="API-simple-strtol">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>simple_strtol</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refentry>

<refentry id="API-simple-strtoull">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>simple_strtoull</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refentry>

<refentry id="API-vsnprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vsnprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
   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>

   Call this function if you are already dealing with a va_list.
   You probably want <function>snprintf</function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-vscnprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vscnprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 &lt;= 0 the function
   returns 0.
   </para><para>

   Call this function if you are already dealing with a va_list.
   You probably want <function>scnprintf</function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-snprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refsect1>
</refentry>

<refentry id="API-scnprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>scnprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 &lt;= 0 the function returns 0.
</para>
</refsect1>
</refentry>

<refentry id="API-vsprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vsprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

   Call this function if you are already dealing with a va_list.
   You probably want <function>sprintf</function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-sprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refsect1>
</refentry>

<refentry id="API-vsscanf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vsscanf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sscanf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

     </sect1>
     <sect1><title>String Manipulation</title>
<!-- All functions are exported at now
X!Ilib/string.c
 -->
<!-- lib/string.c -->
<refentry id="API-strnicmp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strnicmp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strnicmp</refname>
 <refpurpose>
  Case insensitive, length-limited string comparison
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>strnicmp </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strcpy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strncpy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strncpy</refname>
 <refpurpose>
     Copy a length-limited, <constant>NUL-terminated</constant> 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strlcpy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strlcpy</refname>
 <refpurpose>
     Copy a <constant>NUL</constant> terminated 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strcat</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strncat</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strncat</refname>
 <refpurpose>
     Append a length-limited, <constant>NUL-terminated</constant> 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strlcat</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strlcat</refname>
 <refpurpose>
     Append a length-limited, <constant>NUL-terminated</constant> 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strcmp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strncmp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strchr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-strrchr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strrchr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strnchr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-strstrip">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strstrip</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strstrip</refname>
 <refpurpose>
     Removes leading and trailing whitespace from <parameter>s</parameter>.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>strstrip </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strlen</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strnlen</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strspn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strcspn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strpbrk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strsep</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-memset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-memcpy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memcpy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memmove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memcmp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>memcmp</refname>
 <refpurpose>
     Compare two areas of memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memscan</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strstr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-memchr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memchr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

     </sect1>
     <sect1><title>Bit Operations</title>
<!-- include/asm-i386/bitops.h -->
<refentry id="API-set-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>set_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__set_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clear_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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_clear_bit</function> and/or <function>smp_mb__after_clear_bit</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__change_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>change_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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. It may be
   reordered on other architectures than x86.
   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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>test_and_set_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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 may be reordered on other architectures than x86.
   It also implies a memory barrier.
</para>
</refsect1>
</refentry>

<refentry id="API---test-and-set-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__test_and_set_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>test_and_clear_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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 can be reorderdered on other architectures other than x86.
   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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__test_and_clear_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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>
</refentry>

<refentry id="API-test-and-change-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>test_and_change_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>test_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 void * <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-find-first-zero-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_first_zero_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_first_zero_bit</refname>
 <refpurpose>
     find the first zero bit in a memory region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>find_first_zero_bit </function></funcdef>
   <paramdef>const unsigned long * <parameter>addr</parameter></paramdef>
   <paramdef>unsigned <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     The address to start the search at
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The maximum size to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the bit-number of the first zero bit, not the number of the byte
   containing a bit.
</para>
</refsect1>
</refentry>

<refentry id="API-find-next-zero-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_next_zero_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_next_zero_bit</refname>
 <refpurpose>
     find the first zero bit in a memory region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>find_next_zero_bit </function></funcdef>
   <paramdef>const unsigned long * <parameter>addr</parameter></paramdef>
   <paramdef>int <parameter>size</parameter></paramdef>
   <paramdef>int <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     The address to base the search on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The maximum size to search
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     The bitnumber to start searching at
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---ffs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__ffs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__ffs</refname>
 <refpurpose>
     find first 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-find-first-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_first_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_first_bit</refname>
 <refpurpose>
     find the first set bit in a memory region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned <function>find_first_bit </function></funcdef>
   <paramdef>const unsigned long * <parameter>addr</parameter></paramdef>
   <paramdef>unsigned <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     The address to start the search at
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The maximum size to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the bit-number of the first set bit, not the number of the byte
   containing a bit.
</para>
</refsect1>
</refentry>

<refentry id="API-find-next-bit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_next_bit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_next_bit</refname>
 <refpurpose>
     find the first set bit in a memory region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>find_next_bit </function></funcdef>
   <paramdef>const unsigned long * <parameter>addr</parameter></paramdef>
   <paramdef>int <parameter>size</parameter></paramdef>
   <paramdef>int <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     The address to base the search on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The maximum size to search
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     The bitnumber to start searching at
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-ffz">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ffz</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ffz</refname>
 <refpurpose>
     find first zero 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ffs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ffs</refname>
 <refpurpose>
     find first bit set
 </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 above <function>ffz</function> (man ffs).
</para>
</refsect1>
</refentry>

<refentry id="API-fls">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fls</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fls</refname>
 <refpurpose>
     find last bit set
 </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 the same way as <function>ffs</function>.
</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__bitmap_shift_right</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <parameter>shift</parameter></paramdef>
   <paramdef>int <parameter>bits</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>bits</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__bitmap_shift_left</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <parameter>shift</parameter></paramdef>
   <paramdef>int <parameter>bits</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>bits</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-scnprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_scnprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_scnprintf</refname>
 <refpurpose>
     convert bitmap to an ASCII hex string.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bitmap_scnprintf </function></funcdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>unsigned int <parameter>buflen</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>buf</parameter></term>
   <listitem>
    <para>
     byte buffer into which string is placed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buflen</parameter></term>
   <listitem>
    <para>
     reserved size of <parameter>buf</parameter>, in bytes
    </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>
   Exactly <parameter>nmaskbits</parameter> bits are displayed.  Hex digits are grouped into
   comma-separated sets of eight digits per set.
</para>
</refsect1>
</refentry>

<refentry id="API---bitmap-parse">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__bitmap_parse</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_parse_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_parse_user</refname>
 <refpurpose>
   </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>
<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-scnlistprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_scnlistprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_scnlistprintf</refname>
 <refpurpose>
     convert bitmap to list format ASCII string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bitmap_scnlistprintf </function></funcdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>unsigned int <parameter>buflen</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>buf</parameter></term>
   <listitem>
    <para>
     byte buffer into which string is placed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buflen</parameter></term>
   <listitem>
    <para>
     reserved size of <parameter>buf</parameter>, in bytes
    </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.  Consecutively set bits are shown as two hyphen-separated
   decimal numbers, the smallest and largest bit numbers set in
   the range.  Output format is compatible with the format
   accepted as input by <function>bitmap_parselist</function>.
   </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.
</para>
</refsect1>
</refentry>

<refentry id="API-bitmap-parselist">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_parselist</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>bp</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>bp</parameter></term>
   <listitem>
    <para>
     read nul-terminated user string from this buffer
    </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-remap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_remap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <parameter>bits</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>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>

   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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_bitremap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-find-free-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_find_free_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_release_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_allocate_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>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>

<!-- lib/bitmap.c -->
<refentry id="API-bitmap-pos-to-ord">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_pos_to_ord</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_pos_to_ord</refname>
 <refpurpose>
   </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>int <parameter>pos</parameter></paramdef>
   <paramdef>int <parameter>bits</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>bits</parameter>)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bits</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>bits</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 0.  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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>bitmap_ord_to_pos</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>bitmap_ord_to_pos</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>bitmap_ord_to_pos </function></funcdef>
   <paramdef>const unsigned long * <parameter>buf</parameter></paramdef>
   <paramdef>int <parameter>ord</parameter></paramdef>
   <paramdef>int <parameter>bits</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>bits</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), else
   results are undefined.
   </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 return undefined values.  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>bits</parameter> 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_option</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_options</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>memparse</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>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) 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 <constant>K</constant> (for kilobytes, or 1024 bytes),
   <constant>M</constant> (for megabytes, or 1048576 bytes), or <constant>G</constant> (for gigabytes, or
   1073741824).  If the number is suffixed with K, M, or G, then
   the return value is the number multiplied by one kilobyte, one
   megabyte, or one gigabyte, respectively.
</para>
</refsect1>
</refentry>

     </sect1>

     <sect1 id="crc"><title>CRC Functions</title>
<!-- lib/crc7.c -->
<refentry id="API-crc7">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>crc7</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>crc7</refname>
 <refpurpose>
  update the CRC7 for the data buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u8 <function>crc7 </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.
</para>
</refsect1>
</refentry>

<!-- lib/crc16.c -->
<refentry id="API-crc16">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>crc16</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>crc_itu_t</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
<refsect1>
<title>Description</title>
<para>
   Returns the updated CRC value
</para>
</refsect1>
</refentry>

<!-- lib/crc32.c -->
<refentry id="API-crc32-le">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>crc32_le</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>crc32_le</refname>
 <refpurpose>
  Calculate bitwise little-endian Ethernet AUTODIN II CRC32
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 __attribute_pure__ <function>crc32_le </function></funcdef>
   <paramdef>u32 <parameter>crc</parameter></paramdef>
   <paramdef>unsigned char const * <parameter>p</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>
     seed value for computation.  ~0 for Ethernet, sometimes 0 for
     other uses, or the previous crc32 value if computing incrementally.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     pointer to buffer over which CRC is run
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of buffer <parameter>p</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-crc32-be">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>crc32_be</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>crc32_be</refname>
 <refpurpose>
     Calculate bitwise big-endian Ethernet AUTODIN II CRC32
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 __attribute_pure__ <function>crc32_be </function></funcdef>
   <paramdef>u32 <parameter>crc</parameter></paramdef>
   <paramdef>unsigned char const * <parameter>p</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>
     seed value for computation.  ~0 for Ethernet, sometimes 0 for
     other uses, or the previous crc32 value if computing incrementally.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     pointer to buffer over which CRC is run
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of buffer <parameter>p</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- lib/crc-ccitt.c -->
<refentry id="API-crc-ccitt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>crc_ccitt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
  </chapter>

  <chapter id="mm">
     <title>Memory Management in Linux</title>
     <sect1><title>The Slab Cache</title>
<!-- include/linux/slab.h -->
<refentry id="API-kcalloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kcalloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<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-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmalloc_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmalloc_node</refname>
 <refpurpose>
     allocate memory from a specific node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>kmalloc_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 kcalloc).
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     node to allocate from.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <function>kmalloc</function> for non-local nodes, used to allocate from a specific node
   if available. Equivalent to <function>kmalloc</function> in the non-NUMA single-node
   case.
</para>
</refsect1>
</refentry>

<refentry id="API-kzalloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kzalloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

<!-- mm/slab.c -->
<refentry id="API-kmem-cache-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmem_cache_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmem_cache_create</refname>
 <refpurpose>
  Create a cache.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kmem_cache * <function>kmem_cache_create </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>size_t <parameter>align</parameter></paramdef>
   <paramdef>unsigned long <parameter>flags</parameter></paramdef>
   <paramdef>void (*<parameter>ctor</parameter>)
     <funcparams>void*, struct kmem_cache *, unsigned long</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     A string which is used in /proc/slabinfo to identify this cache.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     The size of objects to be created in this cache.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>align</parameter></term>
   <listitem>
    <para>
     The required alignment for the objects.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     SLAB flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ctor</parameter></term>
   <listitem>
    <para>
     A constructor for the objects.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns a ptr to the cache on success, NULL on failure.
   Cannot be called within a int, but can be interrupted.
   The <parameter>ctor</parameter> is run when new pages are allocated by the cache.
   </para><para>

   <parameter>name</parameter> must be valid until the cache is destroyed. This implies that
   the module calling this has to destroy the cache before getting unloaded.
   </para><para>

   The flags are
   </para><para>

   <constant>SLAB_POISON</constant> - Poison the slab with a known test pattern (a5a5a5a5)
   to catch references to uninitialised memory.
   </para><para>

   <constant>SLAB_RED_ZONE</constant> - Insert `Red' zones around the allocated memory to check
   for buffer overruns.
   </para><para>

   <constant>SLAB_HWCACHE_ALIGN</constant> - Align the objects in this cache to a hardware
   cacheline.  This can be beneficial if you're counting cycles as closely
   as davem.
</para>
</refsect1>
</refentry>

<refentry id="API-kmem-cache-shrink">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmem_cache_shrink</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmem_cache_shrink</refname>
 <refpurpose>
     Shrink a cache.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>kmem_cache_shrink </function></funcdef>
   <paramdef>struct kmem_cache * <parameter>cachep</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cachep</parameter></term>
   <listitem>
    <para>
     The cache to shrink.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases as many slabs as possible for a cache.
   To help debugging, a zero exit status indicates all slabs were released.
</para>
</refsect1>
</refentry>

<refentry id="API-kmem-cache-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmem_cache_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kmem_cache_destroy</refname>
 <refpurpose>
     delete a cache
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kmem_cache_destroy </function></funcdef>
   <paramdef>struct kmem_cache * <parameter>cachep</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cachep</parameter></term>
   <listitem>
    <para>
     the cache to destroy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove a &amp;struct kmem_cache object from the slab cache.
   </para><para>

   It is expected this function will be called by a module when it is
   unloaded.  This will remove the cache completely, and avoid a duplicate
   cache being allocated each time a module is loaded and unloaded, if the
   module doesn't have persistent in-kernel storage across loads and unloads.
   </para><para>

   The cache must be empty before calling this function.
   </para><para>

   The caller must guarantee that noone will allocate memory from the cache
   during the <function>kmem_cache_destroy</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-kmem-cache-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmem_cache_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kmem_cache_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfree</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

     </sect1>
     <sect1><title>User Space Memory Access</title>
<!-- include/asm-i386/uaccess.h -->
<refentry id="API-access-ok">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>access_ok</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>access_ok</refname>
 <refpurpose>
  Checks if a user space pointer is valid
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>access_ok </function></funcdef>
   <paramdef> <parameter>type</parameter></paramdef>
   <paramdef> <parameter>addr</parameter></paramdef>
   <paramdef> <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     Type of access: <constant>VERIFY_READ</constant> or <constant>VERIFY_WRITE</constant>.  Note that
     <constant>VERIFY_WRITE</constant> is a superset of <constant>VERIFY_READ</constant> - if it is safe
     to write to a block, it is always safe to read from it.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     User space pointer to start of block to check
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Size of block to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   User context only.  This function may sleep.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks if a pointer to a block of memory in user space is valid.
   </para><para>

   Returns true (nonzero) if the memory block may be valid, false (zero)
   if it is definitely invalid.
   </para><para>

   Note that, depending on architecture, this function probably just
   checks that the pointer is in the user space range - after calling
   this function, memory access functions may still return -EFAULT.
</para>
</refsect1>
</refentry>

<refentry id="API-get-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_user</refname>
 <refpurpose>
     Get a simple variable from user space.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>get_user </function></funcdef>
   <paramdef> <parameter>x</parameter></paramdef>
   <paramdef> <parameter>ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     Variable to store result.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     Source address, in user space.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   User context only.  This function may sleep.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro copies a single simple variable from user space to kernel
   space.  It supports simple types like char and int, but not larger
   data types like structures or arrays.
   </para><para>

   <parameter>ptr</parameter> must have pointer-to-simple-variable type, and the result of
   dereferencing <parameter>ptr</parameter> must be assignable to <parameter>x</parameter> without a cast.
   </para><para>

   Returns zero on success, or -EFAULT on error.
   On error, the variable <parameter>x</parameter> is set to zero.
</para>
</refsect1>
</refentry>

<refentry id="API-put-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>put_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>put_user</refname>
 <refpurpose>
     Write a simple value into user space.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>put_user </function></funcdef>
   <paramdef> <parameter>x</parameter></paramdef>
   <paramdef> <parameter>ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     Value to copy to user space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     Destination address, in user space.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   User context only.  This function may sleep.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro copies a single simple value from kernel space to user
   space.  It supports simple types like char and int, but not larger
   data types like structures or arrays.
   </para><para>

   <parameter>ptr</parameter> must have pointer-to-simple-variable type, and <parameter>x</parameter> must be assignable
   to the result of dereferencing <parameter>ptr</parameter>.
   </para><para>

   Returns zero on success, or -EFAULT on error.
</para>
</refsect1>
</refentry>

<refentry id="API---get-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__get_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__get_user</refname>
 <refpurpose>
     Get a simple variable from user space, with less checking.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>__get_user </function></funcdef>
   <paramdef> <parameter>x</parameter></paramdef>
   <paramdef> <parameter>ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     Variable to store result.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     Source address, in user space.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   User context only.  This function may sleep.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro copies a single simple variable from user space to kernel
   space.  It supports simple types like char and int, but not larger
   data types like structures or arrays.
   </para><para>

   <parameter>ptr</parameter> must have pointer-to-simple-variable type, and the result of
   dereferencing <parameter>ptr</parameter> must be assignable to <parameter>x</parameter> without a cast.
   </para><para>

   Caller must check the pointer with <function>access_ok</function> before calling this
   function.
   </para><para>

   Returns zero on success, or -EFAULT on error.
   On error, the variable <parameter>x</parameter> is set to zero.
</para>
</refsect1>
</refentry>

<refentry id="API---put-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__put_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__put_user</refname>
 <refpurpose>
     Write a simple value into user space, with less checking.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>__put_user </function></funcdef>
   <paramdef> <parameter>x</parameter></paramdef>
   <paramdef> <parameter>ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     Value to copy to user space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     Destination address, in user space.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   User context only.  This function may sleep.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro copies a single simple value from kernel space to user
   space.  It supports simple types like char and int, but not larger
   data types like structures or arrays.
   </para><para>

   <parameter>ptr</parameter> must have pointer-to-simple-variable type, and <parameter>x</parameter> must be assignable
   to the result of dereferencing <parameter>ptr</parameter>.
   </para><para>

   Caller must check the pointer with <function>access_ok</function> before calling this
   function.
   </para><para>

   Returns zero on success, or -EFAULT on error.
</para>
</refsect1>
</refentry>

<refentry id="API---copy-to-user-inatomic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__copy_to_user_inatomic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 __must_check <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 the 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__copy_to_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 __must_check <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__copy_from_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

<refentry id="API-strlen-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strlen_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strlen_user</refname>
 <refpurpose>
     Get the size of a string in user space.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>strlen_user </function></funcdef>
   <paramdef> <parameter>str</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>str</parameter></term>
   <listitem>
    <para>
     The string to measure.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   User context only.  This function may sleep.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Get the size of a NUL-terminated string in user space.
   </para><para>

   Returns the size of the string INCLUDING the terminating NUL.
   On exception, returns 0.
   </para><para>

   If there is a limit on the length of a valid string, you may wish to
   consider using <function>strnlen_user</function> instead.
</para>
</refsect1>
</refentry>

<!-- arch/i386/lib/usercopy.c -->
<refentry id="API---strncpy-from-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__strncpy_from_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__strncpy_from_user</refname>
 <refpurpose>
  Copy a NUL terminated string from userspace, with less checking.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>__strncpy_from_user </function></funcdef>
   <paramdef>char * <parameter>dst</parameter></paramdef>
   <paramdef>const char __user * <parameter>src</parameter></paramdef>
   <paramdef>long <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     Destination address, in kernel space.  This buffer must be at
     least <parameter>count</parameter> bytes long.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     Source address, in user space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     Maximum number of bytes to copy, including the trailing NUL.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies a NUL-terminated string from userspace to kernel space.
   Caller must check the specified block with <function>access_ok</function> before calling
   this function.
   </para><para>

   On success, returns the length of the string (not including the trailing
   NUL).
   </para><para>

   If access to userspace fails, returns -EFAULT (some data may have been
   copied).
   </para><para>

   If <parameter>count</parameter> is smaller than the length of the string, copies <parameter>count</parameter> bytes
   and returns <parameter>count</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-strncpy-from-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strncpy_from_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strncpy_from_user</refname>
 <refpurpose>
     Copy a NUL terminated string from userspace.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>strncpy_from_user </function></funcdef>
   <paramdef>char * <parameter>dst</parameter></paramdef>
   <paramdef>const char __user * <parameter>src</parameter></paramdef>
   <paramdef>long <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     Destination address, in kernel space.  This buffer must be at
     least <parameter>count</parameter> bytes long.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     Source address, in user space.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     Maximum number of bytes to copy, including the trailing NUL.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies a NUL-terminated string from userspace to kernel space.
   </para><para>

   On success, returns the length of the string (not including the trailing
   NUL).
   </para><para>

   If access to userspace fails, returns -EFAULT (some data may have been
   copied).
   </para><para>

   If <parameter>count</parameter> is smaller than the length of the string, copies <parameter>count</parameter> bytes
   and returns <parameter>count</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-clear-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>clear_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__clear_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-strnlen-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>strnlen_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>strnlen_user</refname>
 <refpurpose>
     Get the size of a string in user space.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>strnlen_user </function></funcdef>
   <paramdef>const char __user * <parameter>s</parameter></paramdef>
   <paramdef>long <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>s</parameter></term>
   <listitem>
    <para>
     The string to measure.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     The maximum valid length
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Get the size of a NUL-terminated string in user space.
   </para><para>

   Returns the size of the string INCLUDING the terminating NUL.
   On exception, returns 0.
   If the string is too long, returns a value greater than <parameter>n</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-copy-to-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>copy_to_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 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.
   </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>copy_from_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 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.
   </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>read_cache_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>page_cache_sync_readahead</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>page_cache_async_readahead</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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_ondemand</function> should be called when a page is used which
</para>
</refsect1>
<refsect1>
<title>has the PG_readahead flag</title>
<para>
   this is a marker to suggest that the application
   has used up enough of the readahead window that we should start pulling in
</para>
</refsect1>
</refentry>

<!-- mm/filemap.c -->
<refentry id="API-filemap-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>filemap_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-sync-page-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sync_page_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sync_page_range</refname>
 <refpurpose>
     write and wait on all pages in the passed range
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sync_page_range </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>loff_t <parameter>pos</parameter></paramdef>
   <paramdef>loff_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     target inode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     target address_space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     beginning offset in pages to write
    </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>
   Write and wait upon all the pages in the passed range.  This is a <quote>data
   integrity</quote> operation.  It waits upon in-flight writeout before starting and
   waiting upon new writeout.  If there was an IO error, return it.
   </para><para>

   We need to re-take i_mutex during the generic_osync_inode list walk because
   it is otherwise livelockable.
</para>
</refsect1>
</refentry>

<refentry id="API-sync-page-range-nolock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sync_page_range_nolock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sync_page_range_nolock</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sync_page_range_nolock </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>loff_t <parameter>pos</parameter></paramdef>
   <paramdef>loff_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     target inode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     target address_space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     beginning offset in pages to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of bytes to write
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   Holding i_mutex across <function>sync_page_range_nolock</function> is not a good idea
   as it forces O_SYNC writers to different parts of the same file
   to be serialised right until io completion.
</para>
</refsect1>
</refentry>

<refentry id="API-filemap-fdatawait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>filemap_fdatawait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-add-to-page-cache">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>add_to_page_cache</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>add_to_page_cache</refname>
 <refpurpose>
     add newly allocated pagecache pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>add_to_page_cache </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 newly allocated pagecache pages;
   the page is new, so we can just run <function>SetPageLocked</function> against it.
   The other page state flags were set by <function>rmqueue</function>.
   </para><para>

   This function does not add the page to the LRU.  The caller must do that.
</para>
</refsect1>
</refentry>

<refentry id="API-unlock-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unlock_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unlock_page</refname>
 <refpurpose>
     unlock a locked page
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void fastcall <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
   mechananism 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 first mb is necessary to safely close the critical section opened by the
   <function>TestSetPageLocked</function>, the second 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>end_page_writeback</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__lock_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 fastcall <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>
<refsect1>
<title>Description</title>
<para>
   Ugly. Running <function>sync_page</function> in state TASK_UNINTERRUPTIBLE is scary.  If some
   random driver's requestfn sets TASK_RUNNING, we could busywait.  However
   chances are that on the second loop, the block layer's plug list is empty,
   so <function>sync_page</function> will then return in state TASK_UNINTERRUPTIBLE.
</para>
</refsect1>
</refentry>

<refentry id="API-find-get-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_get_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_get_page</refname>
 <refpurpose>
     find and get a page reference
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>find_get_page </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>unsigned long <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 index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Is there a pagecache struct page at the given (mapping, offset) tuple?
   If yes, increment its refcount and return it; if no, return NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-find-lock-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_lock_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_lock_page</refname>
 <refpurpose>
     locate, pin and lock a pagecache page
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>find_lock_page </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>unsigned long <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 index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Locates the desired pagecache page, locks it, increments its reference
   count and returns its address.
   </para><para>

   Returns zero if the page was not present. <function>find_lock_page</function> may sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-find-or-create-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_or_create_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_or_create_page</refname>
 <refpurpose>
     locate or add a pagecache page
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>find_or_create_page </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>unsigned long <parameter>index</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 page's address_space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>index</parameter></term>
   <listitem>
    <para>
     the page's index into the mapping
    </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>
   Locates a page in the pagecache.  If the page is not present, a new page
   is allocated using <parameter>gfp_mask</parameter> and is added to the pagecache and to the VM's
   LRU list.  The returned page is locked and has its reference count
   incremented.
   </para><para>

   <function>find_or_create_page</function> may sleep, even if <parameter>gfp_flags</parameter> specifies an atomic
   allocation!
   </para><para>

   <function>find_or_create_page</function> returns the desired page's address, or zero on
   memory exhaustion.
</para>
</refsect1>
</refentry>

<refentry id="API-find-get-pages-contig">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_get_pages_contig</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_get_pages_tag</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-grab-cache-page-nowait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>grab_cache_page_nowait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>grab_cache_page_nowait</refname>
 <refpurpose>
     returns locked page at given index in given cache
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>grab_cache_page_nowait </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>unsigned long <parameter>index</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     target address_space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>index</parameter></term>
   <listitem>
    <para>
     the page index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Same as <function>grab_cache_page</function>, but do not wait if the page is unavailable.
   This is intended for speculative data generators, where the data can
   be regenerated if the page couldn't be grabbed.  This routine should
   be safe to call while holding the lock for another page.
   </para><para>

   Clear __GFP_FS when allocating the page to avoid recursion into the fs
   and deadlock against the caller's locked page.
</para>
</refsect1>
</refentry>

<refentry id="API-do-generic-mapping-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>do_generic_mapping_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>do_generic_mapping_read</refname>
 <refpurpose>
     generic file read routine
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>do_generic_mapping_read </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>loff_t * <parameter>ppos</parameter></paramdef>
   <paramdef>read_descriptor_t * <parameter>desc</parameter></paramdef>
   <paramdef>read_actor_t <parameter>actor</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     address_space to be read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>_ra</parameter></term>
   <listitem>
    <para>
     file's readahead state
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     the file to read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ppos</parameter></term>
   <listitem>
    <para>
     current file position
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>desc</parameter></term>
   <listitem>
    <para>
     read_descriptor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>actor</parameter></term>
   <listitem>
    <para>
     read method
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a generic file read routine, and uses the
   mapping-&gt;a_ops-&gt;<function>readpage</function> function for the actual low-level stuff.
   </para><para>

   This is really ugly. But the goto's actually try to clarify some
   of the logic when it comes to error handling etc.
   </para><para>

   Note the struct file* is only passed for the use of readpage.
   It may be NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-file-aio-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_file_aio_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_file_aio_read</refname>
 <refpurpose>
     generic filesystem read routine
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>generic_file_aio_read </function></funcdef>
   <paramdef>struct kiocb * <parameter>iocb</parameter></paramdef>
   <paramdef>const struct iovec * <parameter>iov</parameter></paramdef>
   <paramdef>unsigned long <parameter>nr_segs</parameter></paramdef>
   <paramdef>loff_t <parameter>pos</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>iov</parameter></term>
   <listitem>
    <para>
     io vector request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_segs</parameter></term>
   <listitem>
    <para>
     number of segments in the iovec
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pos</parameter></term>
   <listitem>
    <para>
     current file position
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the <quote><function>read</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>filemap_fault</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refsect1>
</refentry>

<refentry id="API-read-cache-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>read_cache_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>unsigned long <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>
     destination for read data
    </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 then wait for it to become unlocked.
   </para><para>

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

<refentry id="API-try-to-release-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>try_to_release_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

   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).
</para>
</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>

   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).
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   <parameter>gfp_mask</parameter> may go away, and this function may become non-blocking.
</para>
</refsect1>
</refentry>

<!-- mm/memory.c -->
<refentry id="API-vm-insert-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vm_insert_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refsect1>
</refentry>

<refentry id="API-vm-insert-pfn">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vm_insert_pfn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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_inert_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>
</refsect1>
</refentry>

<refentry id="API-remap-pfn-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>remap_pfn_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-unmap-mapping-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unmap_mapping_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>vmtruncate</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-vmtruncate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmtruncate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vmtruncate</refname>
 <refpurpose>
     unmap mappings <quote>freed</quote> by <function>truncate</function> syscall
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vmtruncate </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>loff_t <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     inode of the file used
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     file offset to start truncating
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   NOTE! We have to be ready to update the memory sharing
   between the file and the memory map for a potential last
   incomplete page.  Ugly, but necessary.
</para>
</refsect1>
</refentry>

<!-- mm/vmalloc.c -->
<refentry id="API-vfree">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vfree</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>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>, 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 interrupt context.
</para>
</refsect1>
</refentry>

<refentry id="API-vunmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vunmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmalloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-vmalloc-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmalloc_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmalloc_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-vmalloc-32">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmalloc_32</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vmalloc_32_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>remap_vmalloc_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>Description</title>
<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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>alloc_vm_area</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the area
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function reserves a range of kernel address space, and
   allocates pagetables to map that range.  No actual mappings
   are created.  If the kernel address space is not shared
   between processes, it syncs the pagetable across all
   processes.
</para>
</refsect1>
</refentry>

<!-- mm/page_alloc.c -->
<refentry id="API-find-next-best-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_next_best_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>free_bootmem_with_active_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>free_bootmem_with_active_regions</refname>
 <refpurpose>
     Call free_bootmem_node for each active range
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __init <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 free_bootmem_node
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If an architecture guarantees that all ranges registered with
   <function>add_active_ranges</function> contain no holes and may be freed, this
   this function may be used instead of calling <function>free_bootmem</function> manually.
</para>
</refsect1>
</refentry>

<refentry id="API-sparse-memory-present-with-active-regions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sparse_memory_present_with_active_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 __init <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 with
   <function>add_active_ranges</function> 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-push-node-boundaries">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>push_node_boundaries</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>push_node_boundaries</refname>
 <refpurpose>
     Push node boundaries to at least the requested boundary
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __init <function>push_node_boundaries </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 of the node to push the boundary for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start_pfn</parameter></term>
   <listitem>
    <para>
     The start pfn of the node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end_pfn</parameter></term>
   <listitem>
    <para>
     The end pfn of the node
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   In reserve-based hot-add, mem_map is allocated that is unused until hotadd
   time. Specifically, on x86_64, SRAT will report ranges that can potentially
   be hotplugged even though no physical memory exists. This function allows
   an arch to push out the node boundaries so mem_map is allocated that can
   be used later.
</para>
</refsect1>
</refentry>

<refentry id="API-get-pfn-range-for-nid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_pfn_range_for_nid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 __meminit <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 an arch calling <function>add_active_range</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>absent_pages_in_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 __init <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-add-active-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>add_active_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>add_active_range</refname>
 <refpurpose>
     Register a range of PFNs backed by physical memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __init <function>add_active_range </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 node ID the range resides on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start_pfn</parameter></term>
   <listitem>
    <para>
     The start PFN of the available physical memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end_pfn</parameter></term>
   <listitem>
    <para>
     The end PFN of the available physical memory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   These ranges are stored in an early_node_map[] and later used by
   <function>free_area_init_nodes</function> to calculate zone sizes and holes. If the
   range spans a memory hole, it is up to the architecture to ensure
   the memory is not freed by the bootmem allocator. If possible
   the range being registered will be merged with existing ranges.
</para>
</refsect1>
</refentry>

<refentry id="API-shrink-active-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>shrink_active_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>shrink_active_range</refname>
 <refpurpose>
     Shrink an existing registered range of PFNs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __init <function>shrink_active_range </function></funcdef>
   <paramdef>unsigned int <parameter>nid</parameter></paramdef>
   <paramdef>unsigned long <parameter>old_end_pfn</parameter></paramdef>
   <paramdef>unsigned long <parameter>new_end_pfn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nid</parameter></term>
   <listitem>
    <para>
     The node id the range is on that should be shrunk
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old_end_pfn</parameter></term>
   <listitem>
    <para>
     The old end PFN of the range
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_end_pfn</parameter></term>
   <listitem>
    <para>
     The new PFN of the range
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   i386 with NUMA use <function>alloc_remap</function> to store a node_mem_map on a local node.
   The map is kept at the end physical page range that has already been
   registered with <function>add_active_range</function>. This function allows an arch to shrink
   an existing registered range.
</para>
</refsect1>
</refentry>

<refentry id="API-remove-all-active-ranges">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>remove_all_active_ranges</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>remove_all_active_ranges</refname>
 <refpurpose>
     Remove all currently registered regions
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __init <function>remove_all_active_ranges </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>

   During discovery, it may be found that a table like SRAT is invalid
   and an alternative discovery method must be used. This function removes
   all currently registered regions.
</para>
</refsect1>
</refentry>

<refentry id="API-find-min-pfn-with-active-regions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_min_pfn_with_active_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 __init <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>add_active_range</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-find-max-pfn-with-active-regions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>find_max_pfn_with_active_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>find_max_pfn_with_active_regions</refname>
 <refpurpose>
     Find the maximum PFN registered
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long __init <function>find_max_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 maximum PFN based on information provided via
   <function>add_active_range</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-free-area-init-nodes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>free_area_init_nodes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 __init <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>add_active_range</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>set_dma_reserve</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 __init <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-pages-min">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>setup_per_zone_pages_min</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>setup_per_zone_pages_min</refname>
 <refpurpose>
     called when min_free_kbytes changes.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>setup_per_zone_pages_min </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 pages_{min,low,high} values for each zone are set correctly
   with respect to min_free_kbytes.
</para>
</refsect1>
</refentry>

<!-- mm/mempool.c -->
<refentry id="API-mempool-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mempool_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mempool_resize</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
   <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>new_min_nr</parameter></term>
   <listitem>
    <para>
     the new minimum number of elements guaranteed to be
     allocated for this pool.
    </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 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.
   </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-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mempool_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
   this function only sleeps if the <function>free_fn</function> function sleeps. The caller
   has to guarantee that all elements have been returned to the pool (ie:
   freed) prior to calling <function>mempool_destroy</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-mempool-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mempool_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refentry>

<refentry id="API-mempool-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mempool_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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/page-writeback.c -->
<refentry id="API-balance-dirty-pages-ratelimited-nr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>balance_dirty_pages_ratelimited_nr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>balance_dirty_pages_ratelimited_nr</refname>
 <refpurpose>
  balance dirty memory state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>balance_dirty_pages_ratelimited_nr </function></funcdef>
   <paramdef>struct address_space * <parameter>mapping</parameter></paramdef>
   <paramdef>unsigned long <parameter>nr_pages_dirtied</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>
  <varlistentry>
   <term><parameter>nr_pages_dirtied</parameter></term>
   <listitem>
    <para>
     number of pages which the caller has just 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-write-cache-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>write_cache_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refsect1>
</refentry>

<refentry id="API-generic-writepages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_writepages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>write_one_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

<!-- mm/truncate.c -->
<refentry id="API-truncate-inode-pages-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>truncate_inode_pages_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>truncate_inode_pages_range</refname>
 <refpurpose>
  truncate range of pages specified by start and
 </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
    </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 page
   (if lstart 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>

   When looking at page-&gt;index outside the page lock we need to be careful to
   copy it into a local to avoid races (it could change at any time).
   </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>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Truncate the page cache, removing the pages that are between
   specified offsets (and zeroing out partial page
   (if lstart 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>

   When looking at page-&gt;index outside the page lock we need to be careful to
   copy it into a local to avoid races (it could change at any time).
   </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>
</refsect1>
</refentry>

<refentry id="API-truncate-inode-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>truncate_inode_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refentry>

<refentry id="API-invalidate-mapping-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>invalidate_mapping_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>invalidate_inode_pages2_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 -EIO 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>invalidate_inode_pages2</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 -EIO if any pages could not be invalidated.
</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_init</refname>
 <refpurpose>
  initialise IPC subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <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 system5 IPC resources (semaphores, messages and shared
   memory) are initialised
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-init-ids">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_init_ids</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
   <paramdef>int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ids</parameter></term>
   <listitem>
    <para>
     Identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Number of identifiers
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a size for the ipc identifier range (limited below IPCMNI)
   set up the sequence range to use then allocate and initialise the
   array itself. 
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-init-proc-interface">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_init_proc_interface</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 __init <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_findkey</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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>
     Identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>key</parameter></term>
   <listitem>
    <para>
     The key to find
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Requires ipc_ids.mutex locked.
   Returns the identifier if found or -1 if not.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-addid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_addid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
     new size limit for the id array
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add an entry 'new' to the IPC arrays. The permissions object is
   initialised and the first free entry is set up and the id assigned
   is returned. The list is returned in a locked state on success.
   On failure the list is not locked and -1 is returned.
   </para><para>

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

<refentry id="API-ipc-rmid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_rmid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_rmid</refname>
 <refpurpose>
     remove an IPC identifier
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kern_ipc_perm* <function>ipc_rmid </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>
     identifier set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     Identifier to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The identifier must be valid, and in use. The kernel will panic if
   fed an invalid identifier. The entry is removed and internal
   variables recomputed. The object associated with the identifier
   is returned.
   ipc_ids.mutex and the spinlock for this ID is hold 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_rcu_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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.
   NULL is returned if the allocation fails. 
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-schedule-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_schedule_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_schedule_free</refname>
 <refpurpose>
     free ipc + rcu space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ipc_schedule_free </function></funcdef>
   <paramdef>struct rcu_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     RCU callback structure for queued work
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Since RCU callback function is called in bh,
   we need to defer the vfree to <function>schedule_work</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-ipc-immediate-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_immediate_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc_immediate_free</refname>
 <refpurpose>
     free ipc + rcu space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ipc_immediate_free </function></funcdef>
   <paramdef>struct rcu_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     RCU callback structure that contains pointer to be freed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free from the RCU callback context.
</para>
</refsect1>
</refentry>

<refentry id="API-ipcperms">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipcperms</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 kern_ipc_perm * <parameter>ipcp</parameter></paramdef>
   <paramdef>short <parameter>flag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <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>
</refsect1>
</refentry>

<refentry id="API-kernel-to-ipc64-perm">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kernel_to_ipc64_perm</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc64_perm_to_ipc_perm</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ipc64_perm_to_ipc_perm</refname>
 <refpurpose>
     convert old ipc permissions to new
 </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-parse-version">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ipc_parse_version</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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---kfifo-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__kfifo_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__kfifo_reset</refname>
 <refpurpose>
  removes the entire FIFO contents, no locking version
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__kfifo_reset </function></funcdef>
   <paramdef>struct kfifo * <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     the fifo to be emptied.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_reset</refname>
 <refpurpose>
     removes the entire FIFO contents
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kfifo_reset </function></funcdef>
   <paramdef>struct kfifo * <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     the fifo to be emptied.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_put</refname>
 <refpurpose>
     puts some data into the FIFO
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>kfifo_put </function></funcdef>
   <paramdef>struct kfifo * <parameter>fifo</parameter></paramdef>
   <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     the fifo to be used.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     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>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function copies at most <parameter>len</parameter> bytes from the <parameter>buffer</parameter> into
   the FIFO depending on the free space, and returns the number of
   bytes copied.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_get</refname>
 <refpurpose>
     gets some data from the FIFO
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>kfifo_get </function></funcdef>
   <paramdef>struct kfifo * <parameter>fifo</parameter></paramdef>
   <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     the fifo to be used.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</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>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function copies at most <parameter>len</parameter> bytes from the FIFO into the
   <parameter>buffer</parameter> and returns the number of copied bytes.
</para>
</refsect1>
</refentry>

<refentry id="API---kfifo-len">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__kfifo_len</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__kfifo_len</refname>
 <refpurpose>
     returns the number of bytes available in the FIFO, no locking version
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>__kfifo_len </function></funcdef>
   <paramdef>struct kfifo * <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     the fifo to be used.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-kfifo-len">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_len</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_len</refname>
 <refpurpose>
     returns the number of bytes available in the FIFO
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>kfifo_len </function></funcdef>
   <paramdef>struct kfifo * <parameter>fifo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     the fifo to be used.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- kernel/kfifo.c -->
<refentry id="API-kfifo-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_init</refname>
 <refpurpose>
  allocates a new FIFO using a preallocated buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kfifo * <function>kfifo_init </function></funcdef>
   <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>unsigned int <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>spinlock_t * <parameter>lock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <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>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     get_free_pages mask, passed to <function>kmalloc</function>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     the lock to be used to protect the fifo buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Do NOT pass the kfifo to <function>kfifo_free</function> after use! Simply free the
   &amp;struct kfifo with <function>kfree</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_alloc</refname>
 <refpurpose>
     allocates a new FIFO and its internal buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct kfifo * <function>kfifo_alloc </function></funcdef>
   <paramdef>unsigned int <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>spinlock_t * <parameter>lock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the size of the internal buffer to be allocated.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     get_free_pages mask, passed to <function>kmalloc</function>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     the lock to be used to protect the fifo buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The size will be rounded-up to a power of 2.
</para>
</refsect1>
</refentry>

<refentry id="API-kfifo-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfifo_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfifo_free</refname>
 <refpurpose>
     frees the FIFO
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kfifo_free </function></funcdef>
   <paramdef>struct kfifo * <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-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__kfifo_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__kfifo_put</refname>
 <refpurpose>
     puts some data into the FIFO, no locking version
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>__kfifo_put </function></funcdef>
   <paramdef>struct kfifo * <parameter>fifo</parameter></paramdef>
   <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     the fifo to be used.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     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>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function copies at most <parameter>len</parameter> bytes from the <parameter>buffer</parameter> into
   the FIFO depending on the free space, and returns the number of
   bytes copied.
   </para><para>

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

<refentry id="API---kfifo-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__kfifo_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__kfifo_get</refname>
 <refpurpose>
     gets some data from the FIFO, no locking version
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>__kfifo_get </function></funcdef>
   <paramdef>struct kfifo * <parameter>fifo</parameter></paramdef>
   <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fifo</parameter></term>
   <listitem>
    <para>
     the fifo to be used.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</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>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function copies at most <parameter>len</parameter> bytes from the FIFO into the
   <parameter>buffer</parameter> and returns the number of copied bytes.
   </para><para>

   Note that with only one concurrent reader and one concurrent
   writer, you don't need extra locking to use these functions.
</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_buf_full</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     dentry of parent directory, <constant>NULL</constant> for root directory
    </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_switch_subbuf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_subbufs_consumed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_close</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_mmap_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_alloc_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_create_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_destroy_channel</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_destroy_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_remove_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 fileystem, 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_buf_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>wakeup_readers</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__relay_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_close_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_hotcpu_callback</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>relay_hotcpu_callback</refname>
 <refpurpose>
     CPU hotplug callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __cpuinit <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-file-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_mmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_poll</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_read_subbuf_avail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_read_start_pos</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>relay_file_read_end_pos</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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="netcore">
     <title>Linux Networking</title>
     <sect1><title>Networking Base Types</title>
<!-- include/linux/net.h -->
<refentry id="API-enum-sock-type">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum sock_type</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum sock_type</refname>
 <refpurpose>
  Socket types
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum sock_type {
  SOCK_STREAM,
  SOCK_DGRAM,
  SOCK_RAW,
  SOCK_RDM,
  SOCK_SEQPACKET,
  SOCK_DCCP,
  SOCK_PACKET
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>SOCK_STREAM</term>
      <listitem><para>
stream (connection) socket
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>SOCK_DGRAM</term>
      <listitem><para>
datagram (conn.less) socket
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>SOCK_RAW</term>
      <listitem><para>
raw socket
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>SOCK_RDM</term>
      <listitem><para>
reliably-delivered message
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>SOCK_SEQPACKET</term>
      <listitem><para>
sequential packet socket
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>SOCK_DCCP</term>
      <listitem><para>
Datagram Congestion Control Protocol socket
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>SOCK_PACKET</term>
      <listitem><para>
linux specific way of getting packets at the dev level.
For writing rarp and other similar things on the user level.
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When adding some new socket type please
   grep ARCH_HAS_SOCKET_TYPE include/asm-* /socket.h, at least MIPS
   overrides this enum for binary compat reasons.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-socket">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct socket</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct socket</refname>
 <refpurpose>
     general BSD socket
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct socket {
  socket_state state;
  unsigned long flags;
  const struct proto_ops * ops;
  struct fasync_struct * fasync_list;
  struct file * file;
  struct sock * sk;
  wait_queue_head_t wait;
  short type;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>state</term>
      <listitem><para>
   socket state (<constant>SS_CONNECTED</constant>, etc)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   socket flags (<constant>SOCK_ASYNC_NOSPACE</constant>, etc)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ops</term>
      <listitem><para>
   protocol specific socket operations
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fasync_list</term>
      <listitem><para>
   Asynchronous wake up list
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>file</term>
      <listitem><para>
   File back pointer for gc
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk</term>
      <listitem><para>
   internal networking protocol agnostic socket representation
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>wait</term>
      <listitem><para>
   wait queue for several uses
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type</term>
      <listitem><para>
   socket type (<constant>SOCK_STREAM</constant>, etc)
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

     </sect1>
     <sect1><title>Socket Buffer Functions</title>
<!-- include/linux/skbuff.h -->
<refentry id="API-struct-sk-buff">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct sk_buff</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct sk_buff</refname>
 <refpurpose>
  socket buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct sk_buff {
  struct sk_buff * next;
  struct sk_buff * prev;
  struct sock * sk;
  ktime_t tstamp;
  struct net_device * dev;
  struct dst_entry * dst;
  struct sec_path * sp;
  char cb[48];
  unsigned int len;
  unsigned int data_len;
  __u16 mac_len;
  __u16 hdr_len;
  union {unnamed_union};
  __u32 priority;
  __u8 local_df:1;
  __u8 cloned:1;
  __u8 ip_summed:2;
  __u8 nohdr:1;
  __u8 nfctinfo:3;
  __u8 pkt_type:3;
  __u8 fclone:2;
  __u8 ipvs_property:1;
  __u8 nf_trace:1;
  __be16 protocol;
  void (* destructor) (struct sk_buff *skb);
#if defined(CONFIG_NF_CONNTRACK) || defined(CONFIG_NF_CONNTRACK_MODULE)
  struct nf_conntrack * nfct;
  struct sk_buff * nfct_reasm;
#endif
#ifdef CONFIG_BRIDGE_NETFILTER
  struct nf_bridge_info * nf_bridge;
#endif
  int iif;
  __u16 queue_mapping;
#ifdef CONFIG_NET_SCHED
  __u16 tc_index;
#ifdef CONFIG_NET_CLS_ACT
  __u16 tc_verd;
#endif
#endif
#ifdef CONFIG_NET_DMA
  dma_cookie_t dma_cookie;
#endif
#ifdef CONFIG_NETWORK_SECMARK
  __u32 secmark;
#endif
  __u32 mark;
  sk_buff_data_t transport_header;
  sk_buff_data_t network_header;
  sk_buff_data_t mac_header;
  sk_buff_data_t tail;
  sk_buff_data_t end;
  unsigned char * head;
  unsigned char * data;
  unsigned int truesize;
  atomic_t users;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>next</term>
      <listitem><para>
Next buffer in list
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>prev</term>
      <listitem><para>
Previous buffer in list
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk</term>
      <listitem><para>
Socket we are owned by
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tstamp</term>
      <listitem><para>
Time we arrived
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev</term>
      <listitem><para>
Device we arrived on/are leaving by
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dst</term>
      <listitem><para>
destination entry
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sp</term>
      <listitem><para>
the security path, used for xfrm
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cb[48]</term>
      <listitem><para>
Control buffer. Free for use by every layer. Put private vars here
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>len</term>
      <listitem><para>
Length of actual data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>data_len</term>
      <listitem><para>
Data length
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mac_len</term>
      <listitem><para>
Length of link layer header
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>hdr_len</term>
      <listitem><para>
writable header length of cloned skb
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>{unnamed_union}</term>
      <listitem><para>
anonymous
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>priority</term>
      <listitem><para>
Packet queueing priority
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>local_df</term>
      <listitem><para>
allow local fragmentation
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cloned</term>
      <listitem><para>
Head may be cloned (check refcnt to be sure)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ip_summed</term>
      <listitem><para>
Driver fed us an IP checksum
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>nohdr</term>
      <listitem><para>
Payload reference only, must not modify header
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>nfctinfo</term>
      <listitem><para>
Relationship of this skb to the connection
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pkt_type</term>
      <listitem><para>
Packet class
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fclone</term>
      <listitem><para>
skbuff clone status
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ipvs_property</term>
      <listitem><para>
skbuff is owned by ipvs
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>nf_trace</term>
      <listitem><para>
netfilter packet trace flag
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>protocol</term>
      <listitem><para>
Packet protocol from driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>destructor</term>
      <listitem><para>
Destruct function
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>nfct</term>
      <listitem><para>
Associated connection, if any
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>nfct_reasm</term>
      <listitem><para>
netfilter conntrack re-assembly pointer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>nf_bridge</term>
      <listitem><para>
Saved data about a bridged frame - see br_netfilter.c
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>iif</term>
      <listitem><para>
ifindex of device we arrived on
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>queue_mapping</term>
      <listitem><para>
Queue mapping for multiqueue devices
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tc_index</term>
      <listitem><para>
Traffic control index
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tc_verd</term>
      <listitem><para>
traffic control verdict
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dma_cookie</term>
      <listitem><para>
a cookie to one of several possible DMA operations
done by skb DMA functions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>secmark</term>
      <listitem><para>
security marking
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mark</term>
      <listitem><para>
Generic packet mark
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transport_header</term>
      <listitem><para>
Transport layer header
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>network_header</term>
      <listitem><para>
Network layer header
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mac_header</term>
      <listitem><para>
Link layer header
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tail</term>
      <listitem><para>
Tail pointer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>end</term>
      <listitem><para>
End pointer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>head</term>
      <listitem><para>
Head of buffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>data</term>
      <listitem><para>
Data head pointer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>truesize</term>
      <listitem><para>
Buffer size 
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>users</term>
      <listitem><para>
User count - see {datagram,tcp}.c
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-skb-queue-empty">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_queue_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_queue_empty</refname>
 <refpurpose>
     check if a queue is empty
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_queue_empty </function></funcdef>
   <paramdef>const struct sk_buff_head * <parameter>list</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     queue head
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if the queue is empty, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_get</refname>
 <refpurpose>
     reference buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_get </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to reference
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Makes another reference to a socket buffer and returns a pointer
   to the buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-cloned">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_cloned</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_cloned</refname>
 <refpurpose>
     is the buffer a clone
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_cloned </function></funcdef>
   <paramdef>const struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if the buffer was generated with <function>skb_clone</function> and is
   one of multiple shared copies of the buffer. Cloned buffers are
   shared data so must not be written to under normal circumstances.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-header-cloned">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_header_cloned</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_header_cloned</refname>
 <refpurpose>
     is the header a clone
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_header_cloned </function></funcdef>
   <paramdef>const struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if modifying the header part of the buffer requires
   the data to be copied.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-header-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_header_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_header_release</refname>
 <refpurpose>
     release reference to header
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_header_release </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to operate on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drop a reference to the header part of the buffer.  This is done
   by acquiring a payload reference.  You must not read from the header
   part of skb-&gt;data after this.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-shared">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_shared</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_shared</refname>
 <refpurpose>
     is the buffer shared
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_shared </function></funcdef>
   <paramdef>const struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if more than one person has a reference to this
   buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-share-check">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_share_check</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_share_check</refname>
 <refpurpose>
     check if buffer is shared and if so clone it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_share_check </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>gfp_t <parameter>pri</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to check
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pri</parameter></term>
   <listitem>
    <para>
     priority for memory allocation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the buffer is shared the buffer is cloned and the old copy
   drops a reference. A new clone with a single reference is returned.
   If the buffer is not shared the original buffer is returned. When
   being called from interrupt status or with spinlocks held pri must
   be GFP_ATOMIC.
   </para><para>

   NULL is returned on a memory allocation failure.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-unshare">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_unshare</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_unshare</refname>
 <refpurpose>
     make a copy of a shared buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_unshare </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>gfp_t <parameter>pri</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to check
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pri</parameter></term>
   <listitem>
    <para>
     priority for memory allocation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the socket buffer is a clone then this function creates a new
   copy of the data, drops a reference count on the old copy and returns
   the new copy with the reference count at 1. If the buffer is not a clone
   the original buffer is returned. When called with a spinlock held or
   from interrupt state <parameter>pri</parameter> must be <constant>GFP_ATOMIC</constant>
   </para><para>

   <constant>NULL</constant> is returned on a memory allocation failure.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-peek">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_peek</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_peek</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_peek </function></funcdef>
   <paramdef>struct sk_buff_head * <parameter>list_</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list_</parameter></term>
   <listitem>
    <para>
     list to peek at
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Peek an &amp;sk_buff. Unlike most other operations you _MUST_
   be careful with this one. A peek leaves the buffer on the
   list and someone else may run off with it. You must hold
   the appropriate locks or have a private queue to do this.
   </para><para>

   Returns <constant>NULL</constant> for an empty list or a pointer to the head element.
   The reference count is not incremented and the reference is therefore
   volatile. Use with caution.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-peek-tail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_peek_tail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_peek_tail</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_peek_tail </function></funcdef>
   <paramdef>struct sk_buff_head * <parameter>list_</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list_</parameter></term>
   <listitem>
    <para>
     list to peek at
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Peek an &amp;sk_buff. Unlike most other operations you _MUST_
   be careful with this one. A peek leaves the buffer on the
   list and someone else may run off with it. You must hold
   the appropriate locks or have a private queue to do this.
   </para><para>

   Returns <constant>NULL</constant> for an empty list or a pointer to the tail element.
   The reference count is not incremented and the reference is therefore
   volatile. Use with caution.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-queue-len">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_queue_len</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_queue_len</refname>
 <refpurpose>
     get queue length
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__u32 <function>skb_queue_len </function></funcdef>
   <paramdef>const struct sk_buff_head * <parameter>list_</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list_</parameter></term>
   <listitem>
    <para>
     list to measure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return the length of an &amp;sk_buff queue.
</para>
</refsect1>
</refentry>

<refentry id="API---skb-queue-after">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__skb_queue_after</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__skb_queue_after</refname>
 <refpurpose>
     queue a buffer at the list head
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__skb_queue_after </function></funcdef>
   <paramdef>struct sk_buff_head * <parameter>list</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>prev</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>newsk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     list to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prev</parameter></term>
   <listitem>
    <para>
     place after this buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>newsk</parameter></term>
   <listitem>
    <para>
     buffer to queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Queue a buffer int the middle of a list. This function takes no locks
   and you must therefore hold required locks before calling it.
   </para><para>

   A buffer cannot be placed on two lists at the same time.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_put</refname>
 <refpurpose>
     add data to a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned char * <function>skb_put </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     amount of data to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function extends the used data area of the buffer. If this would
   exceed the total buffer size the kernel will panic. A pointer to the
   first byte of the extra data is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-push">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_push</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_push</refname>
 <refpurpose>
     add data to the start of a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned char * <function>skb_push </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     amount of data to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function extends the used data area of the buffer at the buffer
   start. If this would exceed the total buffer headroom the kernel will
   panic. A pointer to the first byte of the extra data is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-pull">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_pull</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_pull</refname>
 <refpurpose>
     remove data from the start of a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned char * <function>skb_pull </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     amount of data to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function removes data from the start of a buffer, returning
   the memory to the headroom. A pointer to the next data in the buffer
   is returned. Once the data has been pulled future pushes will overwrite
   the old data.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-headroom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_headroom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_headroom</refname>
 <refpurpose>
     bytes at buffer head
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_headroom </function></funcdef>
   <paramdef>const struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return the number of bytes of free space at the head of an &amp;sk_buff.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-tailroom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_tailroom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_tailroom</refname>
 <refpurpose>
     bytes at buffer end
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_tailroom </function></funcdef>
   <paramdef>const struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return the number of bytes of free space at the tail of an sk_buff
</para>
</refsect1>
</refentry>

<refentry id="API-skb-reserve">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_reserve</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_reserve</refname>
 <refpurpose>
     adjust headroom
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_reserve </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to alter
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     bytes to move
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Increase the headroom of an empty &amp;sk_buff by reducing the tail
   room. This is only allowed for an empty buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-trim">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_trim</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_trim</refname>
 <refpurpose>
     remove end from a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_trim </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to alter
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     new length
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Cut the length of a buffer down by removing data from the tail. If
   the buffer is already under the length specified it is not modified.
   The skb must be linear.
</para>
</refsect1>
</refentry>

<refentry id="API-pskb-trim-unique">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pskb_trim_unique</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pskb_trim_unique</refname>
 <refpurpose>
     remove end from a paged unique (not cloned) buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pskb_trim_unique </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to alter
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     new length
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is identical to pskb_trim except that the caller knows that
   the skb is not cloned so we should never get an error due to out-
   of-memory.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-orphan">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_orphan</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_orphan</refname>
 <refpurpose>
     orphan a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_orphan </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to orphan
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a buffer currently has an owner then we call the owner's
   destructor function and make the <parameter>skb</parameter> unowned. The buffer continues
   to exist but is no longer charged to its former owner.
</para>
</refsect1>
</refentry>

<refentry id="API---dev-alloc-skb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__dev_alloc_skb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__dev_alloc_skb</refname>
 <refpurpose>
     allocate an skbuff for receiving
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>__dev_alloc_skb </function></funcdef>
   <paramdef>unsigned int <parameter>length</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     length to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     get_free_pages mask, passed to alloc_skb
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a new &amp;sk_buff and assign it a usage count of one. The
   buffer has unspecified headroom built in. Users should allocate
   the headroom they think they need without accounting for the
   built in space. The built in space is used for optimisations.
   </para><para>

   <constant>NULL</constant> is returned if there is no free memory.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-alloc-skb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_alloc_skb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_alloc_skb</refname>
 <refpurpose>
     allocate an skbuff for receiving
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>dev_alloc_skb </function></funcdef>
   <paramdef>unsigned int <parameter>length</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     length to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a new &amp;sk_buff and assign it a usage count of one. The
   buffer has unspecified headroom built in. Users should allocate
   the headroom they think they need without accounting for the
   built in space. The built in space is used for optimisations.
   </para><para>

   <constant>NULL</constant> is returned if there is no free memory. Although this function
   allocates memory it can be called from an interrupt.
</para>
</refsect1>
</refentry>

<refentry id="API-netdev-alloc-skb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>netdev_alloc_skb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>netdev_alloc_skb</refname>
 <refpurpose>
     allocate an skbuff for rx on a specific device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>netdev_alloc_skb </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>length</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     network device to receive on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     length to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a new &amp;sk_buff and assign it a usage count of one. The
   buffer has unspecified headroom built in. Users should allocate
   the headroom they think they need without accounting for the
   built in space. The built in space is used for optimisations.
   </para><para>

   <constant>NULL</constant> is returned if there is no free memory. Although this function
   allocates memory it can be called from an interrupt.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-clone-writable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_clone_writable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_clone_writable</refname>
 <refpurpose>
     is the header of a clone writable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_clone_writable </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to check
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length up to which to write
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns true if modifying the header part of the cloned buffer
   does not requires the data to be copied.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-cow">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_cow</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_cow</refname>
 <refpurpose>
     copy header of skb when it is required
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_cow </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>headroom</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to cow
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>headroom</parameter></term>
   <listitem>
    <para>
     needed headroom
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the skb passed lacks sufficient headroom or its data part
   is shared, data is reallocated. If reallocation fails, an error
   is returned and original skb is not changed.
   </para><para>

   The result is skb with writable area skb-&gt;head...skb-&gt;tail
   and at least <parameter>headroom</parameter> of space at head.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-padto">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_padto</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_padto</refname>
 <refpurpose>
     pad an skbuff up to a minimal size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_padto </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to pad
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     minimal length
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Pads up a buffer to ensure the trailing bytes exist and are
   blanked. If the buffer already contains sufficient data it
   is untouched. Otherwise it is extended. Returns zero on
   success. The skb is freed on error.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-linearize">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_linearize</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_linearize</refname>
 <refpurpose>
     convert paged skb to linear one
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_linearize </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to linarize
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If there is no free memory -ENOMEM is returned, otherwise zero
   is returned and the old skb data released.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-linearize-cow">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_linearize_cow</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_linearize_cow</refname>
 <refpurpose>
     make sure skb is linear and writable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_linearize_cow </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to process
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If there is no free memory -ENOMEM is returned, otherwise zero
   is returned and the old skb data released.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-postpull-rcsum">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_postpull_rcsum</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_postpull_rcsum</refname>
 <refpurpose>
     update checksum for received skb after pull
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_postpull_rcsum </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>const void * <parameter>start</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     start of data before pull
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of data pulled
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   After doing a pull on a received packet, you need to call this to
   update the CHECKSUM_COMPLETE checksum, or set ip_summed to
   CHECKSUM_NONE so that it can be recomputed from scratch.
</para>
</refsect1>
</refentry>

<refentry id="API-pskb-trim-rcsum">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pskb_trim_rcsum</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pskb_trim_rcsum</refname>
 <refpurpose>
     trim received skb and update checksum
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pskb_trim_rcsum </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to trim
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     new length
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is exactly the same as pskb_trim except that it ensures the
   checksum of received packets are still valid after the operation.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-get-timestamp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_get_timestamp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_get_timestamp</refname>
 <refpurpose>
     get timestamp from a skb
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_get_timestamp </function></funcdef>
   <paramdef>const struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>struct timeval * <parameter>stamp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     skb to get stamp from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>stamp</parameter></term>
   <listitem>
    <para>
     pointer to struct timeval to store stamp in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Timestamps are stored in the skb as offsets to a base timestamp.
   This function converts the offset back to a struct timeval and stores
   it in stamp.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-checksum-complete">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_checksum_complete</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_checksum_complete</refname>
 <refpurpose>
     Calculate checksum of an entire packet
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__sum16 <function>skb_checksum_complete </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     packet to process
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function calculates the checksum over the entire packet plus
   the value of skb-&gt;csum.  The latter can be used to supply the
   checksum of a pseudo header as used by TCP/UDP.  It returns the
   checksum.
   </para><para>

   For protocols that contain complete checksums such as ICMP/TCP/UDP,
   this function can be used to verify that checksum on received
   packets.  In that case the function should return zero if the
   checksum is correct.  In particular, this function will return zero
   if skb-&gt;ip_summed is CHECKSUM_UNNECESSARY which indicates that the
   hardware has already verified the correctness of the checksum.
</para>
</refsect1>
</refentry>

<!-- include/net/sock.h -->
<refentry id="API-struct-sock-common">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct sock_common</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct sock_common</refname>
 <refpurpose>
  minimal network layer representation of sockets
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct sock_common {
  unsigned short skc_family;
  volatile unsigned char skc_state;
  unsigned char skc_reuse;
  int skc_bound_dev_if;
  struct hlist_node skc_node;
  struct hlist_node skc_bind_node;
  atomic_t skc_refcnt;
  unsigned int skc_hash;
  struct proto * skc_prot;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>skc_family</term>
      <listitem><para>
network address family
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>skc_state</term>
      <listitem><para>
Connection state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>skc_reuse</term>
      <listitem><para>
<constant>SO_REUSEADDR</constant> setting
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>skc_bound_dev_if</term>
      <listitem><para>
bound device index if != 0
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>skc_node</term>
      <listitem><para>
main hash linkage for various protocol lookup tables
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>skc_bind_node</term>
      <listitem><para>
bind hash linkage for various protocol lookup tables
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>skc_refcnt</term>
      <listitem><para>
reference count
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>skc_hash</term>
      <listitem><para>
hash value used with various protocol lookup tables
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>skc_prot</term>
      <listitem><para>
protocol handlers inside a network family
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the minimal network layer representation of sockets, the header
   for struct sock and struct inet_timewait_sock.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-sock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct sock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct sock</refname>
 <refpurpose>
     network layer representation of sockets
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct sock {
  struct sock_common __sk_common;
#define sk_family		__sk_common.skc_family
#define sk_state		__sk_common.skc_state
#define sk_reuse		__sk_common.skc_reuse
#define sk_bound_dev_if		__sk_common.skc_bound_dev_if
#define sk_node			__sk_common.skc_node
#define sk_bind_node		__sk_common.skc_bind_node
#define sk_refcnt		__sk_common.skc_refcnt
#define sk_hash			__sk_common.skc_hash
#define sk_prot			__sk_common.skc_prot
  unsigned char sk_shutdown:2;
  unsigned char sk_no_check:2;
  unsigned char sk_userlocks:4;
  unsigned char sk_protocol;
  unsigned short sk_type;
  int sk_rcvbuf;
  socket_lock_t sk_lock;
  struct sk_backlog;
  wait_queue_head_t * sk_sleep;
  struct dst_entry * sk_dst_cache;
  struct xfrm_policy * sk_policy[2];
  rwlock_t sk_dst_lock;
  atomic_t sk_rmem_alloc;
  atomic_t sk_wmem_alloc;
  atomic_t sk_omem_alloc;
  int sk_sndbuf;
  struct sk_buff_head sk_receive_queue;
  struct sk_buff_head sk_write_queue;
  struct sk_buff_head sk_async_wait_queue;
  int sk_wmem_queued;
  int sk_forward_alloc;
  gfp_t sk_allocation;
  int sk_route_caps;
  int sk_gso_type;
  int sk_rcvlowat;
  unsigned long sk_flags;
  unsigned long sk_lingertime;
  struct sk_buff_head sk_error_queue;
  struct proto * sk_prot_creator;
  rwlock_t sk_callback_lock;
  int sk_err;
  int sk_err_soft;
  unsigned short sk_ack_backlog;
  unsigned short sk_max_ack_backlog;
  __u32 sk_priority;
  struct ucred sk_peercred;
  long sk_rcvtimeo;
  long sk_sndtimeo;
  struct sk_filter * sk_filter;
  void * sk_protinfo;
  struct timer_list sk_timer;
  ktime_t sk_stamp;
  struct socket * sk_socket;
  void * sk_user_data;
  struct page * sk_sndmsg_page;
  struct sk_buff * sk_send_head;
  __u32 sk_sndmsg_off;
  int sk_write_pending;
  void * sk_security;
  void (* sk_state_change) (struct sock *sk);
  void (* sk_data_ready) (struct sock *sk, int bytes);
  void (* sk_write_space) (struct sock *sk);
  void (* sk_error_report) (struct sock *sk);
  int (* sk_backlog_rcv) (struct sock *sk,struct sk_buff *skb);
  void (* sk_destruct) (struct sock *sk);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>__sk_common</term>
      <listitem><para>
   shared layout with inet_timewait_sock
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_shutdown</term>
      <listitem><para>
   mask of <constant>SEND_SHUTDOWN</constant> and/or <constant>RCV_SHUTDOWN</constant>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_no_check</term>
      <listitem><para>
   <constant>SO_NO_CHECK</constant> setting, wether or not checkup packets
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_userlocks</term>
      <listitem><para>
   <constant>SO_SNDBUF</constant> and <constant>SO_RCVBUF</constant> settings
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_protocol</term>
      <listitem><para>
   which protocol this socket belongs in this network family
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_type</term>
      <listitem><para>
   socket type (<constant>SOCK_STREAM</constant>, etc)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_rcvbuf</term>
      <listitem><para>
   size of receive buffer in bytes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_lock</term>
      <listitem><para>
   synchronizer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_backlog</term>
      <listitem><para>
   always used with the per-socket spinlock held
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_sleep</term>
      <listitem><para>
   sock wait queue
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_dst_cache</term>
      <listitem><para>
   destination cache
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_policy[2]</term>
      <listitem><para>
   flow policy
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_dst_lock</term>
      <listitem><para>
   destination cache lock
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_rmem_alloc</term>
      <listitem><para>
   receive queue bytes committed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_wmem_alloc</term>
      <listitem><para>
   transmit queue bytes committed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_omem_alloc</term>
      <listitem><para>
   "o<quote> is </quote>option<quote> or </quote>other"
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_sndbuf</term>
      <listitem><para>
   size of send buffer in bytes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_receive_queue</term>
      <listitem><para>
   incoming packets
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_write_queue</term>
      <listitem><para>
   Packet sending queue
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_async_wait_queue</term>
      <listitem><para>
   DMA copied packets
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_wmem_queued</term>
      <listitem><para>
   persistent queue size
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_forward_alloc</term>
      <listitem><para>
   space allocated forward
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_allocation</term>
      <listitem><para>
   allocation mode
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_route_caps</term>
      <listitem><para>
   route capabilities (e.g. <constant>NETIF_F_TSO</constant>)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_gso_type</term>
      <listitem><para>
   GSO type (e.g. <constant>SKB_GSO_TCPV4</constant>)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_rcvlowat</term>
      <listitem><para>
   <constant>SO_RCVLOWAT</constant> setting
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_flags</term>
      <listitem><para>
   <constant>SO_LINGER</constant> (l_onoff), <constant>SO_BROADCAST</constant>, <constant>SO_KEEPALIVE</constant>, <constant>SO_OOBINLINE</constant> settings
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_lingertime</term>
      <listitem><para>
   <constant>SO_LINGER</constant> l_linger setting
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_error_queue</term>
      <listitem><para>
   rarely used
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_prot_creator</term>
      <listitem><para>
   sk_prot of original sock creator (see ipv6_setsockopt, IPV6_ADDRFORM for instance)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_callback_lock</term>
      <listitem><para>
   used with the callbacks in the end of this struct
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_err</term>
      <listitem><para>
   last error
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_err_soft</term>
      <listitem><para>
   errors that don't cause failure but are the cause of a persistent failure not just 'timed out'
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_ack_backlog</term>
      <listitem><para>
   current listen backlog
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_max_ack_backlog</term>
      <listitem><para>
   listen backlog set in <function>listen</function>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_priority</term>
      <listitem><para>
   <constant>SO_PRIORITY</constant> setting
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_peercred</term>
      <listitem><para>
   <constant>SO_PEERCRED</constant> setting
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_rcvtimeo</term>
      <listitem><para>
   <constant>SO_RCVTIMEO</constant> setting
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_sndtimeo</term>
      <listitem><para>
   <constant>SO_SNDTIMEO</constant> setting
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_filter</term>
      <listitem><para>
   socket filtering instructions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_protinfo</term>
      <listitem><para>
   private area, net family specific, when not using slab
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_timer</term>
      <listitem><para>
   sock cleanup timer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_stamp</term>
      <listitem><para>
   time stamp of last packet received
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_socket</term>
      <listitem><para>
   Identd and reporting IO signals
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_user_data</term>
      <listitem><para>
   RPC layer private data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_sndmsg_page</term>
      <listitem><para>
   cached page for sendmsg
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_send_head</term>
      <listitem><para>
   front of stuff to transmit
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_sndmsg_off</term>
      <listitem><para>
   cached offset for sendmsg
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_write_pending</term>
      <listitem><para>
   a write to stream socket waits to start
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_security</term>
      <listitem><para>
   used by security modules
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_state_change</term>
      <listitem><para>
   callback to indicate change in the state of the sock
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_data_ready</term>
      <listitem><para>
   callback to indicate there is data to be processed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_write_space</term>
      <listitem><para>
   callback to indicate there is bf sending space available
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_error_report</term>
      <listitem><para>
   callback to indicate errors (e.g. <constant>MSG_ERRQUEUE</constant>)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_backlog_rcv</term>
      <listitem><para>
   callback to process the backlog
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sk_destruct</term>
      <listitem><para>
   called at sock freeing time, i.e. when all refcnt == 0
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-sk-filter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sk_filter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sk_filter</refname>
 <refpurpose>
     run a packet through a socket filter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sk_filter </function></funcdef>
   <paramdef>struct sock * <parameter>sk</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sk</parameter></term>
   <listitem>
    <para>
     sock associated with &amp;sk_buff
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to filter
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Run the filter code and then cut skb-&gt;data to correct size returned by
   sk_run_filter. If pkt_len is 0 we toss packet. If skb-&gt;len is smaller
   than pkt_len we keep whole skb-&gt;data. This is the socket level
   wrapper to sk_run_filter. It returns 0 if the packet should
   be accepted or -EPERM if the packet should be tossed.
</para>
</refsect1>
</refentry>

<refentry id="API-sk-filter-rcu-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sk_filter_rcu_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sk_filter_rcu_free</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sk_filter_rcu_free </function></funcdef>
   <paramdef>struct rcu_head * <parameter>rcu</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rcu</parameter></term>
   <listitem>
    <para>
     rcu_head that contains the sk_filter to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-sk-filter-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sk_filter_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sk_filter_release</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sk_filter_release </function></funcdef>
   <paramdef>struct sock * <parameter>sk</parameter></paramdef>
   <paramdef>struct sk_filter * <parameter>fp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sk</parameter></term>
   <listitem>
    <para>
     socket
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fp</parameter></term>
   <listitem>
    <para>
     filter to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove a filter from a socket and release its resources.
</para>
</refsect1>
</refentry>

<refentry id="API-sk-eat-skb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sk_eat_skb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sk_eat_skb</refname>
 <refpurpose>
     Release a skb if it is no longer needed
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sk_eat_skb </function></funcdef>
   <paramdef>struct sock * <parameter>sk</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>copied_early</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sk</parameter></term>
   <listitem>
    <para>
     socket to eat this skb from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     socket buffer to eat
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>copied_early</parameter></term>
   <listitem>
    <para>
     flag indicating whether DMA operations copied this data early
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine must be called with interrupts disabled or with the socket
   locked so that the sk_buff queue operation is ok.
</para>
</refsect1>
</refentry>

<!-- net/socket.c -->
<refentry id="API-move-addr-to-kernel">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>move_addr_to_kernel</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>move_addr_to_kernel</refname>
 <refpurpose>
  copy a socket address into kernel space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>move_addr_to_kernel </function></funcdef>
   <paramdef>void __user * <parameter>uaddr</parameter></paramdef>
   <paramdef>int <parameter>ulen</parameter></paramdef>
   <paramdef>void * <parameter>kaddr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>uaddr</parameter></term>
   <listitem>
    <para>
     Address in user space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ulen</parameter></term>
   <listitem>
    <para>
     Length in user space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kaddr</parameter></term>
   <listitem>
    <para>
     Address in kernel space
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The address is copied into kernel space. If the provided address is
   too long an error code of -EINVAL is returned. If the copy gives
   invalid addresses -EFAULT is returned. On a success 0 is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-move-addr-to-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>move_addr_to_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>move_addr_to_user</refname>
 <refpurpose>
     copy an address to user space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>move_addr_to_user </function></funcdef>
   <paramdef>void * <parameter>kaddr</parameter></paramdef>
   <paramdef>int <parameter>klen</parameter></paramdef>
   <paramdef>void __user * <parameter>uaddr</parameter></paramdef>
   <paramdef>int __user * <parameter>ulen</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kaddr</parameter></term>
   <listitem>
    <para>
     kernel space address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>klen</parameter></term>
   <listitem>
    <para>
     length of address in kernel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uaddr</parameter></term>
   <listitem>
    <para>
     user space address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ulen</parameter></term>
   <listitem>
    <para>
     pointer to user length field
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The value pointed to by ulen on entry is the buffer length available.
   This is overwritten with the buffer space used. -EINVAL is returned
   if an overlong buffer is specified or a negative buffer size. -EFAULT
   is returned if either the buffer or the length field are not
   accessible.
   After copying the data up to the limit the user specifies, the true
   length of the data is written over the length limit the user
   specified. Zero is returned for a success.
</para>
</refsect1>
</refentry>

<refentry id="API-sockfd-lookup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sockfd_lookup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sockfd_lookup</refname>
 <refpurpose>
     Go from a file number to its socket slot
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct socket * <function>sockfd_lookup </function></funcdef>
   <paramdef>int <parameter>fd</parameter></paramdef>
   <paramdef>int * <parameter>err</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fd</parameter></term>
   <listitem>
    <para>
     file handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>err</parameter></term>
   <listitem>
    <para>
     pointer to an error code return
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The file handle passed in is locked and the socket it is bound
   too is returned. If an error occurs the err pointer is overwritten
   with a negative errno code and NULL is returned. The function checks
   for both invalid handles and passing a handle which is not a socket.
   </para><para>

   On a success the socket object pointer is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-sock-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sock_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sock_release</refname>
 <refpurpose>
     close a socket
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sock_release </function></funcdef>
   <paramdef>struct socket * <parameter>sock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sock</parameter></term>
   <listitem>
    <para>
     socket to close
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The socket is released from the protocol stack if it has a release
   callback, and the inode is then released if the socket is bound to
   an inode not a file.
</para>
</refsect1>
</refentry>

<refentry id="API-sock-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sock_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sock_register</refname>
 <refpurpose>
     add a socket protocol handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sock_register </function></funcdef>
   <paramdef>const struct net_proto_family * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     description of protocol
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is called by a protocol handler that wants to
   advertise its address family, and have it linked into the
   socket interface. The value ops-&gt;family coresponds to the
   socket system call protocol family.
</para>
</refsect1>
</refentry>

<refentry id="API-sock-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sock_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sock_unregister</refname>
 <refpurpose>
     remove a protocol handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sock_unregister </function></funcdef>
   <paramdef>int <parameter>family</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>family</parameter></term>
   <listitem>
    <para>
     protocol family to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is called by a protocol handler that wants to
   remove its address family, and have it unlinked from the
   new socket creation.
   </para><para>

   If protocol handler is a module, then it can use module reference
   counts to protect against new references. If protocol handler is not
   a module then it needs to provide its own protection in
   the ops-&gt;create routine.
</para>
</refsect1>
</refentry>

<!-- net/core/skbuff.c -->
<refentry id="API-skb-over-panic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_over_panic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_over_panic</refname>
 <refpurpose>
  private function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_over_panic </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>sz</parameter></paramdef>
   <paramdef>void * <parameter>here</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sz</parameter></term>
   <listitem>
    <para>
     size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>here</parameter></term>
   <listitem>
    <para>
     address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Out of line support code for <function>skb_put</function>. Not user callable.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-under-panic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_under_panic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_under_panic</refname>
 <refpurpose>
     private function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_under_panic </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>sz</parameter></paramdef>
   <paramdef>void * <parameter>here</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sz</parameter></term>
   <listitem>
    <para>
     size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>here</parameter></term>
   <listitem>
    <para>
     address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Out of line support code for <function>skb_push</function>. Not user callable.
</para>
</refsect1>
</refentry>

<refentry id="API---alloc-skb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__alloc_skb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__alloc_skb</refname>
 <refpurpose>
     allocate a network buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>__alloc_skb </function></funcdef>
   <paramdef>unsigned int <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
   <paramdef>int <parameter>fclone</parameter></paramdef>
   <paramdef>int <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     allocation mask
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fclone</parameter></term>
   <listitem>
    <para>
     allocate from fclone cache instead of head cache
     and allocate a cloned (child) skb
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     numa node to allocate memory on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a new &amp;sk_buff. The returned buffer has no headroom and a
   tail room of size bytes. The object has a reference count of one.
   The return is the buffer. On a failure the return is <constant>NULL</constant>.
   </para><para>

   Buffers may only be allocated from interrupts using a <parameter>gfp_mask</parameter> of
   <constant>GFP_ATOMIC</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API---netdev-alloc-skb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__netdev_alloc_skb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__netdev_alloc_skb</refname>
 <refpurpose>
     allocate an skbuff for rx on a specific device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>__netdev_alloc_skb </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>length</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     network device to receive on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     length to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     get_free_pages mask, passed to alloc_skb
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a new &amp;sk_buff and assign it a usage count of one. The
   buffer has unspecified headroom built in. Users should allocate
   the headroom they think they need without accounting for the
   built in space. The built in space is used for optimisations.
   </para><para>

   <constant>NULL</constant> is returned if there is no free memory.
</para>
</refsect1>
</refentry>

<refentry id="API---kfree-skb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__kfree_skb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__kfree_skb</refname>
 <refpurpose>
     private function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__kfree_skb </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free an sk_buff. Release anything attached to the buffer.
   Clean the state. This is an internal helper function. Users should
   always call kfree_skb
</para>
</refsect1>
</refentry>

<refentry id="API-kfree-skb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>kfree_skb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>kfree_skb</refname>
 <refpurpose>
     free an sk_buff
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>kfree_skb </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drop a reference to the buffer and free it if the usage count has
   hit zero.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-clone">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_clone</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_clone</refname>
 <refpurpose>
     duplicate an sk_buff
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_clone </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to clone
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     allocation priority
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Duplicate an &amp;sk_buff. The new one is not owned by a socket. Both
   copies share the same packet data but not structure. The new
   buffer has a reference count of 1. If the allocation fails the
   function returns <constant>NULL</constant> otherwise the new buffer is returned.
   </para><para>

   If this function is called from an interrupt <function>gfp_mask</function> must be
   <constant>GFP_ATOMIC</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-copy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_copy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_copy</refname>
 <refpurpose>
     create private copy of an sk_buff
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_copy </function></funcdef>
   <paramdef>const struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to copy
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     allocation priority
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Make a copy of both an &amp;sk_buff and its data. This is used when the
   caller wishes to modify the data and needs a private copy of the
   data to alter. Returns <constant>NULL</constant> on failure or the pointer to the buffer
   on success. The returned buffer has a reference count of 1.
   </para><para>

   As by-product this function converts non-linear &amp;sk_buff to linear
   one, so that &amp;sk_buff becomes completely private and caller is allowed
   to modify all the data of returned buffer. This means that this
   function is not recommended for use in circumstances when only
   header is going to be modified. Use <function>pskb_copy</function> instead.
</para>
</refsect1>
</refentry>

<refentry id="API-pskb-copy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pskb_copy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pskb_copy</refname>
 <refpurpose>
     create copy of an sk_buff with private head.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>pskb_copy </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to copy
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     allocation priority
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Make a copy of both an &amp;sk_buff and part of its data, located
   in header. Fragmented data remain shared. This is used when
   the caller wishes to modify only header of &amp;sk_buff and needs
   private copy of the header to alter. Returns <constant>NULL</constant> on failure
   or the pointer to the buffer on success.
   The returned buffer has a reference count of 1.
</para>
</refsect1>
</refentry>

<refentry id="API-pskb-expand-head">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pskb_expand_head</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pskb_expand_head</refname>
 <refpurpose>
     reallocate header of &amp;sk_buff
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pskb_expand_head </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>nhead</parameter></paramdef>
   <paramdef>int <parameter>ntail</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to reallocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nhead</parameter></term>
   <listitem>
    <para>
     room to add at head
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ntail</parameter></term>
   <listitem>
    <para>
     room to add at tail
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     allocation priority
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Expands (or creates identical copy, if &amp;nhead and &amp;ntail are zero)
   header of skb. &amp;sk_buff itself is not changed. &amp;sk_buff MUST have
   reference count of 1. Returns zero in the case of success or error,
   if expansion failed. In the last case, &amp;sk_buff is not changed.
   </para><para>

   All the pointers pointing into skb header may change and must be
   reloaded after call to this function.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-copy-expand">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_copy_expand</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_copy_expand</refname>
 <refpurpose>
     copy and expand sk_buff
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_copy_expand </function></funcdef>
   <paramdef>const struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>newheadroom</parameter></paramdef>
   <paramdef>int <parameter>newtailroom</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to copy
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>newheadroom</parameter></term>
   <listitem>
    <para>
     new free bytes at head
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>newtailroom</parameter></term>
   <listitem>
    <para>
     new free bytes at tail
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     allocation priority
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Make a copy of both an &amp;sk_buff and its data and while doing so
   allocate additional space.
   </para><para>

   This is used when the caller wishes to modify the data and needs a
   private copy of the data to alter as well as more space for new fields.
   Returns <constant>NULL</constant> on failure or the pointer to the buffer
   on success. The returned buffer has a reference count of 1.
   </para><para>

   You must pass <constant>GFP_ATOMIC</constant> as the allocation priority if this function
   is called from an interrupt.
</para>
</refsect1>
<refsect1>
<title>BUG ALERT</title>
<para>
   ip_summed is not copied. Why does this work? Is it used
   only by netfilter in the cases when checksum is recalculated? --ANK
</para>
</refsect1>
</refentry>

<refentry id="API-skb-pad">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_pad</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_pad</refname>
 <refpurpose>
     zero pad the tail of an skb
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_pad </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>pad</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to pad
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pad</parameter></term>
   <listitem>
    <para>
     space to pad
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Ensure that a buffer is followed by a padding area that is zero
   filled. Used by network drivers which may DMA or transfer data
   beyond the buffer end onto the wire.
   </para><para>

   May return error in out of memory cases. The skb is freed on error.
</para>
</refsect1>
</refentry>

<refentry id="API---pskb-pull-tail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__pskb_pull_tail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__pskb_pull_tail</refname>
 <refpurpose>
     advance tail of skb header
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned char * <function>__pskb_pull_tail </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>delta</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to reallocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>delta</parameter></term>
   <listitem>
    <para>
     number of bytes to advance tail
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The function makes a sense only on a fragmented &amp;sk_buff,
   it expands header moving its tail forward and copying necessary
   data from fragmented part.
   </para><para>

   &amp;sk_buff MUST have reference count of 1.
   </para><para>

   Returns <constant>NULL</constant> (and &amp;sk_buff does not change) if pull failed
   or value of new tail of skb in the case of success.
   </para><para>

   All the pointers pointing into skb header may change and must be
   reloaded after call to this function.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-store-bits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_store_bits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_store_bits</refname>
 <refpurpose>
     store bits from kernel buffer to skb
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_store_bits </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>offset</parameter></paramdef>
   <paramdef>const void * <parameter>from</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     destination buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     offset in destination
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     source buffer
    </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>
   Copy the specified number of bytes from the source buffer to the
   destination skb.  This function handles all the messy bits of
   traversing fragment lists and such.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-dequeue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_dequeue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_dequeue</refname>
 <refpurpose>
     remove from the head of the queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_dequeue </function></funcdef>
   <paramdef>struct sk_buff_head * <parameter>list</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     list to dequeue from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove the head of the list. The list lock is taken so the function
   may be used safely with other locking list functions. The head item is
   returned or <constant>NULL</constant> if the list is empty.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-dequeue-tail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_dequeue_tail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_dequeue_tail</refname>
 <refpurpose>
     remove from the tail of the queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_dequeue_tail </function></funcdef>
   <paramdef>struct sk_buff_head * <parameter>list</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     list to dequeue from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove the tail of the list. The list lock is taken so the function
   may be used safely with other locking list functions. The tail item is
   returned or <constant>NULL</constant> if the list is empty.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-queue-purge">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_queue_purge</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_queue_purge</refname>
 <refpurpose>
     empty a list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_queue_purge </function></funcdef>
   <paramdef>struct sk_buff_head * <parameter>list</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     list to empty
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Delete all buffers on an &amp;sk_buff list. Each buffer is removed from
   the list and one reference dropped. This function takes the list
   lock and is atomic with respect to other list locking functions.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-queue-head">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_queue_head</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_queue_head</refname>
 <refpurpose>
     queue a buffer at the list head
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_queue_head </function></funcdef>
   <paramdef>struct sk_buff_head * <parameter>list</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>newsk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     list to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>newsk</parameter></term>
   <listitem>
    <para>
     buffer to queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Queue a buffer at the start of the list. This function takes the
   list lock and can be used safely with other locking &amp;sk_buff functions
   safely.
   </para><para>

   A buffer cannot be placed on two lists at the same time.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-queue-tail">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_queue_tail</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_queue_tail</refname>
 <refpurpose>
     queue a buffer at the list tail
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_queue_tail </function></funcdef>
   <paramdef>struct sk_buff_head * <parameter>list</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>newsk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     list to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>newsk</parameter></term>
   <listitem>
    <para>
     buffer to queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Queue a buffer at the tail of the list. This function takes the
   list lock and can be used safely with other locking &amp;sk_buff functions
   safely.
   </para><para>

   A buffer cannot be placed on two lists at the same time.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-unlink">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_unlink</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_unlink</refname>
 <refpurpose>
     remove a buffer from a list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_unlink </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>struct sk_buff_head * <parameter>list</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to remove
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     list to use
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove a packet from a list. The list locks are taken and this
   function is atomic with respect to other list locked calls
   </para><para>

   You must know what list the SKB is on.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-append">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_append</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_append</refname>
 <refpurpose>
     append a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_append </function></funcdef>
   <paramdef>struct sk_buff * <parameter>old</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>newsk</parameter></paramdef>
   <paramdef>struct sk_buff_head * <parameter>list</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     buffer to insert after
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>newsk</parameter></term>
   <listitem>
    <para>
     buffer to insert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     list to use
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Place a packet after a given packet in a list. The list locks are taken
   and this function is atomic with respect to other list locked calls.
   A buffer cannot be placed on two lists at the same time.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-insert">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_insert</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_insert</refname>
 <refpurpose>
     insert a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_insert </function></funcdef>
   <paramdef>struct sk_buff * <parameter>old</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>newsk</parameter></paramdef>
   <paramdef>struct sk_buff_head * <parameter>list</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     buffer to insert before
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>newsk</parameter></term>
   <listitem>
    <para>
     buffer to insert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     list to use
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Place a packet before a given packet in a list. The list locks are
   taken and this function is atomic with respect to other list locked
   calls.
   </para><para>

   A buffer cannot be placed on two lists at the same time.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-split">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_split</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_split</refname>
 <refpurpose>
     Split fragmented skb to two parts at length len.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_split </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>skb1</parameter></paramdef>
   <paramdef>const u32 <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     the buffer to split
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>skb1</parameter></term>
   <listitem>
    <para>
     the buffer to receive the second part
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     new length for skb
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-skb-prepare-seq-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_prepare_seq_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_prepare_seq_read</refname>
 <refpurpose>
     Prepare a sequential read of skb data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_prepare_seq_read </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>from</parameter></paramdef>
   <paramdef>unsigned int <parameter>to</parameter></paramdef>
   <paramdef>struct skb_seq_state * <parameter>st</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     the buffer to read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     lower offset of data to be read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     upper offset of data to be read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>st</parameter></term>
   <listitem>
    <para>
     state variable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initializes the specified state variable. Must be called before
   invoking <function>skb_seq_read</function> for the first time.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-seq-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_seq_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_seq_read</refname>
 <refpurpose>
     Sequentially read skb data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>skb_seq_read </function></funcdef>
   <paramdef>unsigned int <parameter>consumed</parameter></paramdef>
   <paramdef>const u8 ** <parameter>data</parameter></paramdef>
   <paramdef>struct skb_seq_state * <parameter>st</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>consumed</parameter></term>
   <listitem>
    <para>
     number of bytes consumed by the caller so far
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     destination pointer for data to be returned
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>st</parameter></term>
   <listitem>
    <para>
     state variable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reads a block of skb data at &amp;consumed relative to the
   lower offset specified to <function>skb_prepare_seq_read</function>. Assigns
   the head of the data block to &amp;data and returns the length
   of the block or 0 if the end of the skb data or the upper
   offset has been reached.
   </para><para>

   The caller is not required to consume all of the data
   returned, i.e. &amp;consumed is typically set to the number
   of bytes already consumed and the next call to
   <function>skb_seq_read</function> will return the remaining part of the block.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   Fragment lists within fragments are not implemented
   at the moment, state-&gt;root_skb could be replaced with
   a stack for this purpose.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   Fragment lists within fragments are not implemented
   at the moment, state-&gt;root_skb could be replaced with
   a stack for this purpose.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-abort-seq-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_abort_seq_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_abort_seq_read</refname>
 <refpurpose>
     Abort a sequential read of skb data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_abort_seq_read </function></funcdef>
   <paramdef>struct skb_seq_state * <parameter>st</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>st</parameter></term>
   <listitem>
    <para>
     state variable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Must be called if <function>skb_seq_read</function> was not called until it
   returned 0.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-find-text">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_find_text</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_find_text</refname>
 <refpurpose>
     Find a text pattern in skb data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>skb_find_text </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>from</parameter></paramdef>
   <paramdef>unsigned int <parameter>to</parameter></paramdef>
   <paramdef>struct ts_config * <parameter>config</parameter></paramdef>
   <paramdef>struct ts_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     the buffer to look in
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     search offset
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     search limit
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>config</parameter></term>
   <listitem>
    <para>
     textsearch configuration
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     uninitialized textsearch state variable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds a pattern in the skb data according to the specified
   textsearch configuration. Use <function>textsearch_next</function> to retrieve
   subsequent occurrences of the pattern. Returns the offset
   to the first occurrence or UINT_MAX if no match was found.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-append-datato-frags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_append_datato_frags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_append_datato_frags</refname>
 <refpurpose>
     append the user data to a skb
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_append_datato_frags </function></funcdef>
   <paramdef>struct sock * <parameter>sk</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int (*<parameter>getfrag</parameter>)
     <funcparams>void *from, char *to, int offset, 					int len, int odd, struct sk_buff *skb</funcparams></paramdef>
   <paramdef>void * <parameter>from</parameter></paramdef>
   <paramdef>int <parameter>length</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sk</parameter></term>
   <listitem>
    <para>
     sock  structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     skb structure to be appened with user data.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>getfrag</parameter></term>
   <listitem>
    <para>
     call back function to be used for getting the user data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     pointer to user message iov
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     length of the iov message
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This procedure append the user data in the fragment part
   of the skb if any page alloc fails user this procedure returns  -ENOMEM
</para>
</refsect1>
</refentry>

<refentry id="API-skb-pull-rcsum">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_pull_rcsum</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_pull_rcsum</refname>
 <refpurpose>
     pull skb and update receive checksum
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned char * <function>skb_pull_rcsum </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of data pulled
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function performs an skb_pull on the packet and updates
   update the CHECKSUM_COMPLETE checksum.  It should be used on
   receive path processing instead of skb_pull unless you know
   that the checksum difference is zero (e.g., a valid IP header)
   or you are setting ip_summed to CHECKSUM_NONE.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-segment">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_segment</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_segment</refname>
 <refpurpose>
     Perform protocol segmentation on skb.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_segment </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>features</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to segment
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>features</parameter></term>
   <listitem>
    <para>
     features for the output path (see dev-&gt;features)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function performs segmentation on the given skb.  It returns
   the segment at the given position.  It returns NULL if there are
   no more segments to generate, or when an error is encountered.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-to-sgvec">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_to_sgvec</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_to_sgvec</refname>
 <refpurpose>
     Fill a scatter-gather list from a socket buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_to_sgvec </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>struct scatterlist * <parameter>sg</parameter></paramdef>
   <paramdef>int <parameter>offset</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     Socket buffer containing the buffers to be mapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sg</parameter></term>
   <listitem>
    <para>
     The scatter-gather list to map into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     The offset into the buffer's contents to start mapping
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     Length of buffer space to be mapped
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Fill the specified scatter-gather list with mappings/pointers into a
   region of the buffer space attached to a socket buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-cow-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_cow_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_cow_data</refname>
 <refpurpose>
     Check that a socket buffer's data buffers are writable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_cow_data </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>tailbits</parameter></paramdef>
   <paramdef>struct sk_buff ** <parameter>trailer</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     The socket buffer to check.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tailbits</parameter></term>
   <listitem>
    <para>
     Amount of trailing space to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>trailer</parameter></term>
   <listitem>
    <para>
     Returned pointer to the skb where the <parameter>tailbits</parameter> space begins
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Make sure that the data buffers attached to a socket buffer are
   writable. If they are not, private copies are made of the data buffers
   and the socket buffer is set to use these instead.
   </para><para>

   If <parameter>tailbits</parameter> is given, make sure that there is space to write <parameter>tailbits</parameter>
   bytes of data beyond current end of socket buffer.  <parameter>trailer</parameter> will be
   set to point to the skb in which this space begins.
   </para><para>

   The number of scatterlist elements required to completely map the
   COW'd and extended socket buffer will be returned.
</para>
</refsect1>
</refentry>

<!-- net/core/sock.c -->
<refentry id="API-sk-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sk_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sk_alloc</refname>
 <refpurpose>
  All socket objects are allocated here
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sock * <function>sk_alloc </function></funcdef>
   <paramdef>int <parameter>family</parameter></paramdef>
   <paramdef>gfp_t <parameter>priority</parameter></paramdef>
   <paramdef>struct proto * <parameter>prot</parameter></paramdef>
   <paramdef>int <parameter>zero_it</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>family</parameter></term>
   <listitem>
    <para>
     protocol family
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>priority</parameter></term>
   <listitem>
    <para>
     for allocation (<constant>GFP_KERNEL</constant>, <constant>GFP_ATOMIC</constant>, etc)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prot</parameter></term>
   <listitem>
    <para>
     struct proto associated with this new sock instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>zero_it</parameter></term>
   <listitem>
    <para>
     if we should zero the newly allocated sock
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-sk-wait-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sk_wait_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sk_wait_data</refname>
 <refpurpose>
     wait for data to arrive at sk_receive_queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sk_wait_data </function></funcdef>
   <paramdef>struct sock * <parameter>sk</parameter></paramdef>
   <paramdef>long * <parameter>timeo</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sk</parameter></term>
   <listitem>
    <para>
     sock to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeo</parameter></term>
   <listitem>
    <para>
     for how long
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Now socket state including sk-&gt;sk_err is changed only under lock,
   hence we may omit checks after joining wait queue.
   We check receive queue before <function>schedule</function> only as optimization;
   it is very likely that <function>release_sock</function> added new data.
</para>
</refsect1>
</refentry>

<!-- net/core/datagram.c -->
<refentry id="API-skb-recv-datagram">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_recv_datagram</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_recv_datagram</refname>
 <refpurpose>
  Receive a datagram skbuff
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_recv_datagram </function></funcdef>
   <paramdef>struct sock * <parameter>sk</parameter></paramdef>
   <paramdef>unsigned <parameter>flags</parameter></paramdef>
   <paramdef>int <parameter>noblock</parameter></paramdef>
   <paramdef>int * <parameter>err</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sk</parameter></term>
   <listitem>
    <para>
     socket
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     MSG_ flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>noblock</parameter></term>
   <listitem>
    <para>
     blocking operation?
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>err</parameter></term>
   <listitem>
    <para>
     error code returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Get a datagram skbuff, understands the peeking, nonblocking wakeups
   and possible races. This replaces identical code in packet, raw and
   udp, as well as the IPX AX.25 and Appletalk. It also finally fixes
   the long standing peek and read race for datagram sockets. If you
   alter this routine remember it must be re-entrant.
   </para><para>

   This function will lock the socket if a skb is returned, so the caller
   needs to unlock the socket in that case (usually by calling
   skb_free_datagram)
   </para><para>

   * It does not lock socket since today. This function is
   * free of race conditions. This measure should/can improve
   * significantly datagram socket latencies at high loads,
   * when data copying to user space takes lots of time.
   * (BTW I've just killed the last <function>cli</function> in IP/IPv6/core/netlink/packet
   *  8) Great win.)
   *			                    --ANK (980729)
   </para><para>

   The order of the tests when we find no data waiting are specified
   quite explicitly by POSIX 1003.1g, don't change them without having
   the standard around please.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-kill-datagram">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_kill_datagram</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_kill_datagram</refname>
 <refpurpose>
     Free a datagram skbuff forcibly
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>skb_kill_datagram </function></funcdef>
   <paramdef>struct sock * <parameter>sk</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sk</parameter></term>
   <listitem>
    <para>
     socket
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     datagram skbuff
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     MSG_ flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function frees a datagram skbuff that was received by
   skb_recv_datagram.  The flags argument must match the one
   used for skb_recv_datagram.
   </para><para>

   If the MSG_PEEK flag is set, and the packet is still on the
   receive queue of the socket, it will be taken off the queue
   before it is freed.
   </para><para>

   This function currently only disables BH when acquiring the
   sk_receive_queue lock.  Therefore it must not be used in a
   context where that lock is acquired in an IRQ context.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-copy-datagram-iovec">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_copy_datagram_iovec</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_copy_datagram_iovec</refname>
 <refpurpose>
     Copy a datagram to an iovec.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_copy_datagram_iovec </function></funcdef>
   <paramdef>const struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>offset</parameter></paramdef>
   <paramdef>struct iovec * <parameter>to</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to copy
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     offset in the buffer to start copying from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     io vector to copy to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     amount of data to copy from buffer to iovec
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the iovec is modified during the copy.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-copy-and-csum-datagram-iovec">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_copy_and_csum_datagram_iovec</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_copy_and_csum_datagram_iovec</refname>
 <refpurpose>
     Copy and checkum skb to user iovec.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>skb_copy_and_csum_datagram_iovec </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>hlen</parameter></paramdef>
   <paramdef>struct iovec * <parameter>iov</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     skbuff
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hlen</parameter></term>
   <listitem>
    <para>
     hardware length
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>iov</parameter></term>
   <listitem>
    <para>
     io vector
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Caller _must_ check that skb will fit to this iovec.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0       - success.
   -EINVAL - checksum failure.
   -EFAULT - fault during copy. Beware, in this case iovec
   can be modified!
</para>
</refsect1>
</refentry>

<refentry id="API-datagram-poll">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>datagram_poll</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>datagram_poll</refname>
 <refpurpose>
     generic datagram poll
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>datagram_poll </function></funcdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
   <paramdef>struct socket * <parameter>sock</parameter></paramdef>
   <paramdef>poll_table * <parameter>wait</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     file struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sock</parameter></term>
   <listitem>
    <para>
     socket
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wait</parameter></term>
   <listitem>
    <para>
     poll table
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Datagram poll</title>
<para>
   Again totally generic. This also handles
   sequenced packet sockets providing the socket receive queue
   is only ever holding data ready to receive.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   when you _don't_ use this routine for this protocol,
   and you use a different write policy from <function>sock_writeable</function>
   then please supply your own write_space callback.
</para>
</refsect1>
</refentry>

<!-- net/core/stream.c -->
<refentry id="API-sk-stream-write-space">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sk_stream_write_space</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sk_stream_write_space</refname>
 <refpurpose>
  stream socket write_space callback.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sk_stream_write_space </function></funcdef>
   <paramdef>struct sock * <parameter>sk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sk</parameter></term>
   <listitem>
    <para>
     socket
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>FIXME</title>
<para>
   write proper description
</para>
</refsect1>
</refentry>

<refentry id="API-sk-stream-wait-connect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sk_stream_wait_connect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sk_stream_wait_connect</refname>
 <refpurpose>
     Wait for a socket to get into the connected state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sk_stream_wait_connect </function></funcdef>
   <paramdef>struct sock * <parameter>sk</parameter></paramdef>
   <paramdef>long * <parameter>timeo_p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sk</parameter></term>
   <listitem>
    <para>
     sock to wait on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeo_p</parameter></term>
   <listitem>
    <para>
     for how long to wait
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Must be called with the socket locked.
</para>
</refsect1>
</refentry>

<refentry id="API-sk-stream-wait-memory">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sk_stream_wait_memory</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sk_stream_wait_memory</refname>
 <refpurpose>
     Wait for more memory for a socket
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sk_stream_wait_memory </function></funcdef>
   <paramdef>struct sock * <parameter>sk</parameter></paramdef>
   <paramdef>long * <parameter>timeo_p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sk</parameter></term>
   <listitem>
    <para>
     socket to wait for memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeo_p</parameter></term>
   <listitem>
    <para>
     for how long
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Socket Filter</title>
<!-- net/core/filter.c -->
<refentry id="API-sk-run-filter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sk_run_filter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sk_run_filter</refname>
 <refpurpose>
  run a filter on a socket
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>sk_run_filter </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>struct sock_filter * <parameter>filter</parameter></paramdef>
   <paramdef>int <parameter>flen</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to run the filter on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filter</parameter></term>
   <listitem>
    <para>
     filter to apply
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flen</parameter></term>
   <listitem>
    <para>
     length of filter
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Decode and apply filter instructions to the skb-&gt;data.
   Return length to keep, 0 for none. skb is the data we are
   filtering, filter is the array of filter instructions, and
   len is the number of filter blocks in the array.
</para>
</refsect1>
</refentry>

<refentry id="API-sk-chk-filter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sk_chk_filter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sk_chk_filter</refname>
 <refpurpose>
     verify socket filter code
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sk_chk_filter </function></funcdef>
   <paramdef>struct sock_filter * <parameter>filter</parameter></paramdef>
   <paramdef>int <parameter>flen</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filter</parameter></term>
   <listitem>
    <para>
     filter to verify
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flen</parameter></term>
   <listitem>
    <para>
     length of filter
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check the user's filter code. If we let some ugly
   filter code slip through kaboom! The filter must contain
   no references or jumps that are out of range, no illegal
   instructions, and must end with a RET instruction.
   </para><para>

   All jumps are forward as they are not signed.
   </para><para>

   Returns 0 if the rule set is legal or -EINVAL if not.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Generic Network Statistics</title>
<!-- include/linux/gen_stats.h -->
<refentry id="API-struct-gnet-stats-basic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct gnet_stats_basic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct gnet_stats_basic</refname>
 <refpurpose>
  byte/packet throughput statistics
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct gnet_stats_basic {
  __u64 bytes;
  __u32 packets;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>bytes</term>
      <listitem><para>
number of seen bytes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>packets</term>
      <listitem><para>
number of seen packets
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-gnet-stats-rate-est">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct gnet_stats_rate_est</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct gnet_stats_rate_est</refname>
 <refpurpose>
     rate estimator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct gnet_stats_rate_est {
  __u32 bps;
  __u32 pps;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>bps</term>
      <listitem><para>
   current byte rate
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pps</term>
      <listitem><para>
   current packet rate
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-gnet-stats-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct gnet_stats_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct gnet_stats_queue</refname>
 <refpurpose>
     queuing statistics
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct gnet_stats_queue {
  __u32 qlen;
  __u32 backlog;
  __u32 drops;
  __u32 requeues;
  __u32 overlimits;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>qlen</term>
      <listitem><para>
   queue length
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>backlog</term>
      <listitem><para>
   backlog size of queue
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>drops</term>
      <listitem><para>
   number of dropped packets
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>requeues</term>
      <listitem><para>
   number of requeues
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>overlimits</term>
      <listitem><para>
   number of enqueues over the limit
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-gnet-estimator">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct gnet_estimator</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct gnet_estimator</refname>
 <refpurpose>
     rate estimator configuration
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct gnet_estimator {
  signed char interval;
  unsigned char ewma_log;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>interval</term>
      <listitem><para>
   sampling period
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ewma_log</term>
      <listitem><para>
   the log of measurement window weight
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- net/core/gen_stats.c -->
<refentry id="API-gnet-stats-start-copy-compat">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gnet_stats_start_copy_compat</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gnet_stats_start_copy_compat</refname>
 <refpurpose>
  start dumping procedure in compatibility mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gnet_stats_start_copy_compat </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>int <parameter>tc_stats_type</parameter></paramdef>
   <paramdef>int <parameter>xstats_type</parameter></paramdef>
   <paramdef>spinlock_t * <parameter>lock</parameter></paramdef>
   <paramdef>struct gnet_dump * <parameter>d</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     socket buffer to put statistics TLVs into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     TLV type for top level statistic TLV
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tc_stats_type</parameter></term>
   <listitem>
    <para>
     TLV type for backward compatibility struct tc_stats TLV
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>xstats_type</parameter></term>
   <listitem>
    <para>
     TLV type for backward compatibility xstats TLV
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     statistics lock
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>d</parameter></term>
   <listitem>
    <para>
     dumping handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initializes the dumping handle, grabs the statistic lock and appends
   an empty TLV header to the socket buffer for use a container for all
   other statistic TLVS.
   </para><para>

   The dumping handle is marked to be in backward compatibility mode telling
   all <function>gnet_stats_copy_XXX</function> functions to fill a local copy of struct tc_stats.
   </para><para>

   Returns 0 on success or -1 if the room in the socket buffer was not sufficient.
</para>
</refsect1>
</refentry>

<refentry id="API-gnet-stats-start-copy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gnet_stats_start_copy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gnet_stats_start_copy</refname>
 <refpurpose>
     start dumping procedure in compatibility mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gnet_stats_start_copy </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>spinlock_t * <parameter>lock</parameter></paramdef>
   <paramdef>struct gnet_dump * <parameter>d</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     socket buffer to put statistics TLVs into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     TLV type for top level statistic TLV
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     statistics lock
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>d</parameter></term>
   <listitem>
    <para>
     dumping handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initializes the dumping handle, grabs the statistic lock and appends
   an empty TLV header to the socket buffer for use a container for all
   other statistic TLVS.
   </para><para>

   Returns 0 on success or -1 if the room in the socket buffer was not sufficient.
</para>
</refsect1>
</refentry>

<refentry id="API-gnet-stats-copy-basic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gnet_stats_copy_basic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gnet_stats_copy_basic</refname>
 <refpurpose>
     copy basic statistics into statistic TLV
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gnet_stats_copy_basic </function></funcdef>
   <paramdef>struct gnet_dump * <parameter>d</parameter></paramdef>
   <paramdef>struct gnet_stats_basic * <parameter>b</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>d</parameter></term>
   <listitem>
    <para>
     dumping handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>b</parameter></term>
   <listitem>
    <para>
     basic statistics
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Appends the basic statistics to the top level TLV created by
   <function>gnet_stats_start_copy</function>.
   </para><para>

   Returns 0 on success or -1 with the statistic lock released
   if the room in the socket buffer was not sufficient.
</para>
</refsect1>
</refentry>

<refentry id="API-gnet-stats-copy-rate-est">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gnet_stats_copy_rate_est</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gnet_stats_copy_rate_est</refname>
 <refpurpose>
     copy rate estimator statistics into statistics TLV
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gnet_stats_copy_rate_est </function></funcdef>
   <paramdef>struct gnet_dump * <parameter>d</parameter></paramdef>
   <paramdef>struct gnet_stats_rate_est * <parameter>r</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>d</parameter></term>
   <listitem>
    <para>
     dumping handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     rate estimator statistics
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Appends the rate estimator statistics to the top level TLV created by
   <function>gnet_stats_start_copy</function>.
   </para><para>

   Returns 0 on success or -1 with the statistic lock released
   if the room in the socket buffer was not sufficient.
</para>
</refsect1>
</refentry>

<refentry id="API-gnet-stats-copy-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gnet_stats_copy_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gnet_stats_copy_queue</refname>
 <refpurpose>
     copy queue statistics into statistics TLV
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gnet_stats_copy_queue </function></funcdef>
   <paramdef>struct gnet_dump * <parameter>d</parameter></paramdef>
   <paramdef>struct gnet_stats_queue * <parameter>q</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>d</parameter></term>
   <listitem>
    <para>
     dumping handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     queue statistics
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Appends the queue statistics to the top level TLV created by
   <function>gnet_stats_start_copy</function>.
   </para><para>

   Returns 0 on success or -1 with the statistic lock released
   if the room in the socket buffer was not sufficient.
</para>
</refsect1>
</refentry>

<refentry id="API-gnet-stats-copy-app">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gnet_stats_copy_app</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gnet_stats_copy_app</refname>
 <refpurpose>
     copy application specific statistics into statistics TLV
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gnet_stats_copy_app </function></funcdef>
   <paramdef>struct gnet_dump * <parameter>d</parameter></paramdef>
   <paramdef>void * <parameter>st</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>d</parameter></term>
   <listitem>
    <para>
     dumping handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>st</parameter></term>
   <listitem>
    <para>
     application specific statistics data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Appends the application sepecific statistics to the top level TLV created by
   <function>gnet_stats_start_copy</function> and remembers the data for XSTATS if the dumping
   handle is in backward compatibility mode.
   </para><para>

   Returns 0 on success or -1 with the statistic lock released
   if the room in the socket buffer was not sufficient.
</para>
</refsect1>
</refentry>

<refentry id="API-gnet-stats-finish-copy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gnet_stats_finish_copy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gnet_stats_finish_copy</refname>
 <refpurpose>
     finish dumping procedure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gnet_stats_finish_copy </function></funcdef>
   <paramdef>struct gnet_dump * <parameter>d</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>d</parameter></term>
   <listitem>
    <para>
     dumping handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Corrects the length of the top level TLV to include all TLVs added
   by <function>gnet_stats_copy_XXX</function> calls. Adds the backward compatibility TLVs
   if <function>gnet_stats_start_copy_compat</function> was used and releases the statistics
   lock.
   </para><para>

   Returns 0 on success or -1 with the statistic lock released
   if the room in the socket buffer was not sufficient.
</para>
</refsect1>
</refentry>

<!-- net/core/gen_estimator.c -->
<refentry id="API-gen-new-estimator">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gen_new_estimator</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gen_new_estimator</refname>
 <refpurpose>
  create a new rate estimator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gen_new_estimator </function></funcdef>
   <paramdef>struct gnet_stats_basic * <parameter>bstats</parameter></paramdef>
   <paramdef>struct gnet_stats_rate_est * <parameter>rate_est</parameter></paramdef>
   <paramdef>spinlock_t * <parameter>stats_lock</parameter></paramdef>
   <paramdef>struct rtattr * <parameter>opt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bstats</parameter></term>
   <listitem>
    <para>
     basic statistics
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rate_est</parameter></term>
   <listitem>
    <para>
     rate estimator statistics
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>stats_lock</parameter></term>
   <listitem>
    <para>
     statistics lock
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>opt</parameter></term>
   <listitem>
    <para>
     rate estimator configuration TLV
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new rate estimator with &amp;bstats as source and &amp;rate_est
   as destination. A new timer with the interval specified in the
   configuration TLV is created. Upon each interval, the latest statistics
   will be read from &amp;bstats and the estimated rate will be stored in
   &amp;rate_est with the statistics lock grabed during this period.
   </para><para>

   Returns 0 on success or a negative error code.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   Called under rtnl_mutex
</para>
</refsect1>
</refentry>

<refentry id="API-gen-kill-estimator">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gen_kill_estimator</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gen_kill_estimator</refname>
 <refpurpose>
     remove a rate estimator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>gen_kill_estimator </function></funcdef>
   <paramdef>struct gnet_stats_basic * <parameter>bstats</parameter></paramdef>
   <paramdef>struct gnet_stats_rate_est * <parameter>rate_est</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bstats</parameter></term>
   <listitem>
    <para>
     basic statistics
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rate_est</parameter></term>
   <listitem>
    <para>
     rate estimator statistics
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes the rate estimator specified by &amp;bstats and &amp;rate_est
   and deletes the timer.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   Called under rtnl_mutex
</para>
</refsect1>
</refentry>

<refentry id="API-gen-replace-estimator">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gen_replace_estimator</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gen_replace_estimator</refname>
 <refpurpose>
     replace rate estimator configruation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gen_replace_estimator </function></funcdef>
   <paramdef>struct gnet_stats_basic * <parameter>bstats</parameter></paramdef>
   <paramdef>struct gnet_stats_rate_est * <parameter>rate_est</parameter></paramdef>
   <paramdef>spinlock_t * <parameter>stats_lock</parameter></paramdef>
   <paramdef>struct rtattr * <parameter>opt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bstats</parameter></term>
   <listitem>
    <para>
     basic statistics
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rate_est</parameter></term>
   <listitem>
    <para>
     rate estimator statistics
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>stats_lock</parameter></term>
   <listitem>
    <para>
     statistics lock
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>opt</parameter></term>
   <listitem>
    <para>
     rate estimator configuration TLV
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Replaces the configuration of a rate estimator by calling
   <function>gen_kill_estimator</function> and <function>gen_new_estimator</function>.
   </para><para>

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

     </sect1>
     <sect1><title>SUN RPC subsystem</title>
<!-- The !D functionality is not perfect, garbage has to be protected by comments
net/sunrpc/sunrpc_syms.c-->
<!-- net/sunrpc/xdr.c -->
<refentry id="API-xdr-encode-opaque-fixed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>xdr_encode_opaque_fixed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>xdr_encode_opaque_fixed</refname>
 <refpurpose>
  Encode fixed length opaque data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__be32 * <function>xdr_encode_opaque_fixed </function></funcdef>
   <paramdef>__be32 * <parameter>p</parameter></paramdef>
   <paramdef>const void * <parameter>ptr</parameter></paramdef>
   <paramdef>unsigned int <parameter>nbytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     pointer to current position in XDR buffer.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer to data to encode (or NULL)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nbytes</parameter></term>
   <listitem>
    <para>
     size of data.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copy the array of data of length nbytes at ptr to the XDR buffer
   at position p, then align to the next 32-bit boundary by padding
   with zero bytes (see RFC1832).
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   if ptr is NULL, only the padding is performed.
   </para><para>

   Returns the updated current XDR buffer position
</para>
</refsect1>
</refentry>

<refentry id="API-xdr-encode-opaque">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>xdr_encode_opaque</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>xdr_encode_opaque</refname>
 <refpurpose>
     Encode variable length opaque data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__be32 * <function>xdr_encode_opaque </function></funcdef>
   <paramdef>__be32 * <parameter>p</parameter></paramdef>
   <paramdef>const void * <parameter>ptr</parameter></paramdef>
   <paramdef>unsigned int <parameter>nbytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     pointer to current position in XDR buffer.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer to data to encode (or NULL)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nbytes</parameter></term>
   <listitem>
    <para>
     size of data.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the updated current XDR buffer position
</para>
</refsect1>
</refentry>

<refentry id="API-xdr-init-encode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>xdr_init_encode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>xdr_init_encode</refname>
 <refpurpose>
     Initialize a struct xdr_stream for sending data.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>xdr_init_encode </function></funcdef>
   <paramdef>struct xdr_stream * <parameter>xdr</parameter></paramdef>
   <paramdef>struct xdr_buf * <parameter>buf</parameter></paramdef>
   <paramdef>__be32 * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>xdr</parameter></term>
   <listitem>
    <para>
     pointer to xdr_stream struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     pointer to XDR buffer in which to encode data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     current pointer inside XDR buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   at the moment the RPC client only passes the length of our
   scratch buffer in the xdr_buf's header kvec. Previously this
   meant we needed to call <function>xdr_adjust_iovec</function> after encoding the
   data. With the new scheme, the xdr_stream manages the details
   of the buffer length, and takes care of adjusting the kvec
   length for us.
</para>
</refsect1>
</refentry>

<refentry id="API-xdr-reserve-space">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>xdr_reserve_space</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>xdr_reserve_space</refname>
 <refpurpose>
     Reserve buffer space for sending
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__be32 * <function>xdr_reserve_space </function></funcdef>
   <paramdef>struct xdr_stream * <parameter>xdr</parameter></paramdef>
   <paramdef>size_t <parameter>nbytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>xdr</parameter></term>
   <listitem>
    <para>
     pointer to xdr_stream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nbytes</parameter></term>
   <listitem>
    <para>
     number of bytes to reserve
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks that we have enough buffer space to encode 'nbytes' more
   bytes of data. If so, update the total xdr_buf length, and
   adjust the length of the current kvec.
</para>
</refsect1>
</refentry>

<refentry id="API-xdr-write-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>xdr_write_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>xdr_write_pages</refname>
 <refpurpose>
     Insert a list of pages into an XDR buffer for sending
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>xdr_write_pages </function></funcdef>
   <paramdef>struct xdr_stream * <parameter>xdr</parameter></paramdef>
   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
   <paramdef>unsigned int <parameter>base</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>xdr</parameter></term>
   <listitem>
    <para>
     pointer to xdr_stream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     list of pages
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     offset of first byte
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of data in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-xdr-init-decode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>xdr_init_decode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>xdr_init_decode</refname>
 <refpurpose>
     Initialize an xdr_stream for decoding data.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>xdr_init_decode </function></funcdef>
   <paramdef>struct xdr_stream * <parameter>xdr</parameter></paramdef>
   <paramdef>struct xdr_buf * <parameter>buf</parameter></paramdef>
   <paramdef>__be32 * <parameter>p</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>xdr</parameter></term>
   <listitem>
    <para>
     pointer to xdr_stream struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     pointer to XDR buffer from which to decode data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     current pointer inside XDR buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-xdr-inline-decode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>xdr_inline_decode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>xdr_inline_decode</refname>
 <refpurpose>
     Retrieve non-page XDR data to decode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__be32 * <function>xdr_inline_decode </function></funcdef>
   <paramdef>struct xdr_stream * <parameter>xdr</parameter></paramdef>
   <paramdef>size_t <parameter>nbytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>xdr</parameter></term>
   <listitem>
    <para>
     pointer to xdr_stream struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nbytes</parameter></term>
   <listitem>
    <para>
     number of bytes of data to decode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check if the input buffer is long enough to enable us to decode
   'nbytes' more bytes of data starting at the current position.
   If so return the current pointer, then update the current
   pointer position.
</para>
</refsect1>
</refentry>

<refentry id="API-xdr-read-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>xdr_read_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>xdr_read_pages</refname>
 <refpurpose>
     Ensure page-based XDR data to decode is aligned at current pointer position
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>xdr_read_pages </function></funcdef>
   <paramdef>struct xdr_stream * <parameter>xdr</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>xdr</parameter></term>
   <listitem>
    <para>
     pointer to xdr_stream struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes of page data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Moves data beyond the current pointer position from the XDR head[] buffer
   into the page list. Any data that lies beyond current position + <quote>len</quote>
   bytes is moved into the XDR tail[].
</para>
</refsect1>
</refentry>

<refentry id="API-xdr-enter-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>xdr_enter_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>xdr_enter_page</refname>
 <refpurpose>
     decode data from the XDR page
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>xdr_enter_page </function></funcdef>
   <paramdef>struct xdr_stream * <parameter>xdr</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>xdr</parameter></term>
   <listitem>
    <para>
     pointer to xdr_stream struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes of page data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Moves data beyond the current pointer position from the XDR head[] buffer
   into the page list. Any data that lies beyond current position + <quote>len</quote>
   bytes is moved into the XDR tail[]. The current pointer is then
   repositioned at the beginning of the first XDR page.
</para>
</refsect1>
</refentry>

<!-- net/sunrpc/svcsock.c -->
<refentry id="API-svc-print-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>svc_print_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>svc_print_addr</refname>
 <refpurpose>
  Format rq_addr field for printing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>svc_print_addr </function></funcdef>
   <paramdef>struct svc_rqst * <parameter>rqstp</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rqstp</parameter></term>
   <listitem>
    <para>
     svc_rqst struct containing address to print
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     target buffer for formatted address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of target buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-svc-reserve">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>svc_reserve</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>svc_reserve</refname>
 <refpurpose>
     change the space reserved for the reply to a request.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>svc_reserve </function></funcdef>
   <paramdef>struct svc_rqst * <parameter>rqstp</parameter></paramdef>
   <paramdef>int <parameter>space</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rqstp</parameter></term>
   <listitem>
    <para>
     The request in question
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>space</parameter></term>
   <listitem>
    <para>
     new max space to reserve
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each request reserves some space on the output queue of the socket
   to make sure the reply fits.  This function reduces that reserved
   space to be the amount of space used already, plus <parameter>space</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-svc-makesock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>svc_makesock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>svc_makesock</refname>
 <refpurpose>
     Make a socket for nfsd and lockd
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>svc_makesock </function></funcdef>
   <paramdef>struct svc_serv * <parameter>serv</parameter></paramdef>
   <paramdef>int <parameter>protocol</parameter></paramdef>
   <paramdef>unsigned short <parameter>port</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>serv</parameter></term>
   <listitem>
    <para>
     RPC server structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>protocol</parameter></term>
   <listitem>
    <para>
     transport protocol to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     port to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     requested socket characteristics
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- net/sunrpc/sched.c -->
<refentry id="API-rpc-wake-up">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rpc_wake_up</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rpc_wake_up</refname>
 <refpurpose>
  wake up all rpc_tasks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>rpc_wake_up </function></funcdef>
   <paramdef>struct rpc_wait_queue * <parameter>queue</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>queue</parameter></term>
   <listitem>
    <para>
     rpc_wait_queue on which the tasks are sleeping
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Grabs queue-&gt;lock
</para>
</refsect1>
</refentry>

<refentry id="API-rpc-wake-up-status">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>rpc_wake_up_status</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>rpc_wake_up_status</refname>
 <refpurpose>
     wake up all rpc_tasks and set their status value.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>rpc_wake_up_status </function></funcdef>
   <paramdef>struct rpc_wait_queue * <parameter>queue</parameter></paramdef>
   <paramdef>int <parameter>status</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>queue</parameter></term>
   <listitem>
    <para>
     rpc_wait_queue on which the tasks are sleeping
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>status</parameter></term>
   <listitem>
    <para>
     status value to set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Grabs queue-&gt;lock
</para>
</refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="netdev">
     <title>Network device support</title>
     <sect1><title>Driver Support</title>
<!-- net/core/dev.c -->
<refentry id="API-dev-add-pack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_add_pack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_add_pack</refname>
 <refpurpose>
  add packet handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dev_add_pack </function></funcdef>
   <paramdef>struct packet_type * <parameter>pt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pt</parameter></term>
   <listitem>
    <para>
     packet type declaration
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add a protocol handler to the networking stack. The passed &amp;packet_type
   is linked into kernel lists and may not be freed until it has been
   removed from the kernel lists.
   </para><para>

   This call does not sleep therefore it can not
   guarantee all CPU's that are in middle of receiving packets
   will see the new packet type (until the next received packet).
</para>
</refsect1>
</refentry>

<refentry id="API---dev-remove-pack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__dev_remove_pack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__dev_remove_pack</refname>
 <refpurpose>
     remove packet handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__dev_remove_pack </function></funcdef>
   <paramdef>struct packet_type * <parameter>pt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pt</parameter></term>
   <listitem>
    <para>
     packet type declaration
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove a protocol handler that was previously added to the kernel
   protocol handlers by <function>dev_add_pack</function>. The passed &amp;packet_type is removed
   from the kernel lists and can be freed or reused once this function
   returns.
   </para><para>

   The packet type might still be in use by receivers
   and must not be freed until after all the CPU's have gone
   through a quiescent state.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-remove-pack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_remove_pack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_remove_pack</refname>
 <refpurpose>
     remove packet handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dev_remove_pack </function></funcdef>
   <paramdef>struct packet_type * <parameter>pt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pt</parameter></term>
   <listitem>
    <para>
     packet type declaration
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove a protocol handler that was previously added to the kernel
   protocol handlers by <function>dev_add_pack</function>. The passed &amp;packet_type is removed
   from the kernel lists and can be freed or reused once this function
   returns.
   </para><para>

   This call sleeps to guarantee that no CPU is looking at the packet
   type after return.
</para>
</refsect1>
</refentry>

<refentry id="API-netdev-boot-setup-check">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>netdev_boot_setup_check</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>netdev_boot_setup_check</refname>
 <refpurpose>
     check boot time settings
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>netdev_boot_setup_check </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the netdevice
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check boot time settings for the device.
   The found settings are set for the device to be used
   later in the device probing.
   Returns 0 if no settings found, 1 if they are.
</para>
</refsect1>
</refentry>

<refentry id="API---dev-get-by-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__dev_get_by_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__dev_get_by_name</refname>
 <refpurpose>
     find a device by its name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct net_device * <function>__dev_get_by_name </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name to find
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Find an interface by name. Must be called under RTNL semaphore
   or <parameter>dev_base_lock</parameter>. If the name is found a pointer to the device
   is returned. If the name is not found then <constant>NULL</constant> is returned. The
   reference counters are not incremented so the caller must be
   careful with locks.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-get-by-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_get_by_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_get_by_name</refname>
 <refpurpose>
     find a device by its name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct net_device * <function>dev_get_by_name </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name to find
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Find an interface by name. This can be called from any
   context and does its own locking. The returned handle has
   the usage count incremented and the caller must use <function>dev_put</function> to
   release it when it is no longer needed. <constant>NULL</constant> is returned if no
   matching device is found.
</para>
</refsect1>
</refentry>

<refentry id="API---dev-get-by-index">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__dev_get_by_index</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__dev_get_by_index</refname>
 <refpurpose>
     find a device by its ifindex
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct net_device * <function>__dev_get_by_index </function></funcdef>
   <paramdef>int <parameter>ifindex</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ifindex</parameter></term>
   <listitem>
    <para>
     index of device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Search for an interface by index. Returns <constant>NULL</constant> if the device
   is not found or a pointer to the device. The device has not
   had its reference counter increased so the caller must be careful
   about locking. The caller must hold either the RTNL semaphore
   or <parameter>dev_base_lock</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-get-by-index">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_get_by_index</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_get_by_index</refname>
 <refpurpose>
     find a device by its ifindex
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct net_device * <function>dev_get_by_index </function></funcdef>
   <paramdef>int <parameter>ifindex</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ifindex</parameter></term>
   <listitem>
    <para>
     index of device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Search for an interface by index. Returns NULL if the device
   is not found or a pointer to the device. The device returned has
   had a reference added and the pointer is safe until the user calls
   dev_put to indicate they have finished with it.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-getbyhwaddr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_getbyhwaddr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_getbyhwaddr</refname>
 <refpurpose>
     find a device by its hardware address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct net_device * <function>dev_getbyhwaddr </function></funcdef>
   <paramdef>unsigned short <parameter>type</parameter></paramdef>
   <paramdef>char * <parameter>ha</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     media type of device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ha</parameter></term>
   <listitem>
    <para>
     hardware address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Search for an interface by MAC address. Returns NULL if the device
   is not found or a pointer to the device. The caller must hold the
   rtnl semaphore. The returned device has not had its ref count increased
   and the caller must therefore be careful about locking
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
   If the API was consistent this would be __dev_get_by_hwaddr
</para>
</refsect1>
</refentry>

<refentry id="API-dev-get-by-flags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_get_by_flags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_get_by_flags</refname>
 <refpurpose>
     find any device with given flags
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct net_device * <function>dev_get_by_flags </function></funcdef>
   <paramdef>unsigned short <parameter>if_flags</parameter></paramdef>
   <paramdef>unsigned short <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>if_flags</parameter></term>
   <listitem>
    <para>
     IFF_* values
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     bitmask of bits in if_flags to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Search for any interface with the given flags. Returns NULL if a device
   is not found or a pointer to the device. The device returned has
   had a reference added and the pointer is safe until the user calls
   dev_put to indicate they have finished with it.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-valid-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_valid_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_valid_name</refname>
 <refpurpose>
     check if name is okay for network device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dev_valid_name </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Network device names need to be valid file names to
   to allow sysfs to work.  We also disallow any kind of
   whitespace.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-alloc-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_alloc_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_alloc_name</refname>
 <refpurpose>
     allocate a name for a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dev_alloc_name </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name format string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Passed a format string - eg <quote>lt<constant>d</constant></quote> it will try and find a suitable
   id. It scans list of devices to build up a free map, then chooses
   the first empty slot. The caller must hold the dev_base or rtnl lock
   while allocating the name and adding the device in order to avoid
   duplicates.
   Limited to bits_per_byte * page size devices (ie 32K on most platforms).
   Returns the number of the unit assigned or a negative errno code.
</para>
</refsect1>
</refentry>

<refentry id="API-netdev-features-change">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>netdev_features_change</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>netdev_features_change</refname>
 <refpurpose>
     device changes features
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>netdev_features_change </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to cause notification
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called to indicate a device has changed features.
</para>
</refsect1>
</refentry>

<refentry id="API-netdev-state-change">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>netdev_state_change</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>netdev_state_change</refname>
 <refpurpose>
     device changes state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>netdev_state_change </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to cause notification
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called to indicate a device has changed state. This function calls
   the notifier chains for netdev_chain and sends a NEWLINK message
   to the routing socket.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-load">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_load</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_load</refname>
 <refpurpose>
     load a network module
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dev_load </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of interface
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a network interface is not present and the process has suitable
   privileges this function loads the module. If module loading is not
   available in this kernel then it becomes a nop.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_open</refname>
 <refpurpose>
     prepare an interface for use.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dev_open </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to open
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Takes a device from down to up state. The device's private open
   function is invoked and then the multicast lists are loaded. Finally
   the device is moved into the up state and a <constant>NETDEV_UP</constant> message is
   sent to the netdev notifier chain.
   </para><para>

   Calling this function on an active interface is a nop. On a failure
   a negative errno code is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-close">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_close</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_close</refname>
 <refpurpose>
     shutdown an interface.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dev_close </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to shutdown
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function moves an active device into down state. A
   <constant>NETDEV_GOING_DOWN</constant> is sent to the netdev notifier chain. The device
   is then deactivated and finally a <constant>NETDEV_DOWN</constant> is sent to the notifier
   chain.
</para>
</refsect1>
</refentry>

<refentry id="API-register-netdevice-notifier">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_netdevice_notifier</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_netdevice_notifier</refname>
 <refpurpose>
     register a network notifier block
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_netdevice_notifier </function></funcdef>
   <paramdef>struct notifier_block * <parameter>nb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nb</parameter></term>
   <listitem>
    <para>
     notifier
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register a notifier to be called when network device events occur.
   The notifier passed is linked into the kernel structures and must
   not be reused until it has been unregistered. A negative errno code
   is returned on a failure.
   </para><para>

   When registered all registration and up events are replayed
   to the new notifier to allow device to have a race free
   view of the network device list.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-netdevice-notifier">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_netdevice_notifier</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_netdevice_notifier</refname>
 <refpurpose>
     unregister a network notifier block
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>unregister_netdevice_notifier </function></funcdef>
   <paramdef>struct notifier_block * <parameter>nb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nb</parameter></term>
   <listitem>
    <para>
     notifier
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregister a notifier previously registered by
   <function>register_netdevice_notifier</function>. The notifier is unlinked into the
   kernel structures and may then be reused. A negative errno code
   is returned on a failure.
</para>
</refsect1>
</refentry>

<refentry id="API-skb-gso-segment">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>skb_gso_segment</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>skb_gso_segment</refname>
 <refpurpose>
     Perform segmentation on skb.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sk_buff * <function>skb_gso_segment </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>int <parameter>features</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to segment
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>features</parameter></term>
   <listitem>
    <para>
     features for the output path (see dev-&gt;features)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function segments the given skb and returns a list of segments.
   </para><para>

   It may return NULL if the skb requires no segmentation.  This is
   only possible when GSO is used for verifying header integrity.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-queue-xmit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_queue_xmit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_queue_xmit</refname>
 <refpurpose>
     transmit a buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dev_queue_xmit </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to transmit
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Queue a buffer for transmission to a network device. The caller must
   have set the device and priority and built the buffer before calling
   this function. The function can be called from an interrupt.
   </para><para>

   A negative errno code is returned on a failure. A success does not
   guarantee the frame will be transmitted as it may be dropped due
   to congestion or traffic shaping.
   </para><para>

   -----------------------------------------------------------------------------------
   I notice this method can also return errors from the queue disciplines,
   including NET_XMIT_DROP, which is a positive value.  So, errors can also
   be positive.
   </para><para>

   Regardless of the return value, the skb is consumed, so it is currently
   difficult to retry a send to this method.  (You can bump the ref count
   before sending to hold a reference for retry if you are careful.)
   </para><para>

   When calling this method, interrupts MUST be enabled.  This is because
   the BH enable code must have IRQs enabled so that it will not deadlock.
   --BLG
</para>
</refsect1>
</refentry>

<refentry id="API-netif-rx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>netif_rx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>netif_rx</refname>
 <refpurpose>
     post buffer to the network code
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>netif_rx </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     buffer to post
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function receives a packet from a device driver and queues it for
   the upper (protocol) levels to process.  It always succeeds. The buffer
   may be dropped during processing for congestion control or by the
   protocol layers.
</para>
</refsect1>
<refsect1>
<title>return values</title>
<para>
   NET_RX_SUCCESS	(no congestion)
   NET_RX_CN_LOW   (low congestion)
   NET_RX_CN_MOD   (moderate congestion)
   NET_RX_CN_HIGH  (high congestion)
   NET_RX_DROP     (packet was dropped)
</para>
</refsect1>
</refentry>

<refentry id="API-register-gifconf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_gifconf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_gifconf</refname>
 <refpurpose>
     register a SIOCGIF handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_gifconf </function></funcdef>
   <paramdef>unsigned int <parameter>family</parameter></paramdef>
   <paramdef>gifconf_func_t * <parameter>gifconf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>family</parameter></term>
   <listitem>
    <para>
     Address family
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gifconf</parameter></term>
   <listitem>
    <para>
     Function handler
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register protocol dependent address dumping routines. The handler
   that is passed must not be freed or reused until it has been replaced
   by another handler.
</para>
</refsect1>
</refentry>

<refentry id="API-netdev-set-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>netdev_set_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>netdev_set_master</refname>
 <refpurpose>
     set up master/slave pair
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>netdev_set_master </function></funcdef>
   <paramdef>struct net_device * <parameter>slave</parameter></paramdef>
   <paramdef>struct net_device * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>slave</parameter></term>
   <listitem>
    <para>
     slave device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     new master device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Changes the master device of the slave. Pass <constant>NULL</constant> to break the
   bonding. The caller must hold the RTNL semaphore. On a failure
   a negative errno code is returned. On success the reference counts
   are adjusted, <constant>RTM_NEWLINK</constant> is sent to the routing socket and the
   function returns zero.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-set-promiscuity">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_set_promiscuity</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_set_promiscuity</refname>
 <refpurpose>
     update promiscuity count on a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dev_set_promiscuity </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>inc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>inc</parameter></term>
   <listitem>
    <para>
     modifier
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add or remove promiscuity from a device. While the count in the device
   remains above zero the interface remains promiscuous. Once it hits zero
   the device reverts back to normal filtering operation. A negative inc
   value is used to drop promiscuity on the device.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-set-allmulti">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_set_allmulti</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_set_allmulti</refname>
 <refpurpose>
     update allmulti count on a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>dev_set_allmulti </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>inc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>inc</parameter></term>
   <listitem>
    <para>
     modifier
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add or remove reception of all multicast frames to a device. While the
   count in the device remains above zero the interface remains listening
   to all interfaces. Once it hits zero the device reverts back to normal
   filtering operation. A negative <parameter>inc</parameter> value is used to drop the counter
   when releasing a resource needing all multicasts.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-unicast-delete">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_unicast_delete</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_unicast_delete</refname>
 <refpurpose>
     Release secondary unicast address.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dev_unicast_delete </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>addr</parameter></paramdef>
   <paramdef>int <parameter>alen</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     address to delete
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alen</parameter></term>
   <listitem>
    <para>
     length of <parameter>addr</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release reference to a secondary unicast address and remove it
   from the device if the reference count drops to zero.
   </para><para>

   The caller must hold the rtnl_mutex.
</para>
</refsect1>
</refentry>

<refentry id="API-dev-unicast-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dev_unicast_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dev_unicast_add</refname>
 <refpurpose>
     add a secondary unicast address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dev_unicast_add </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>addr</parameter></paramdef>
   <paramdef>int <parameter>alen</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     address to delete
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alen</parameter></term>
   <listitem>
    <para>
     length of <parameter>addr</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add a secondary unicast address to the device or increase
   the reference count if it already exists.
   </para><para>

   The caller must hold the rtnl_mutex.
</para>
</refsect1>
</refentry>

<refentry id="API-register-netdevice">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_netdevice</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_netdevice</refname>
 <refpurpose>
     register a network device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_netdevice </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Take a completed network device structure and add it to the kernel
   interfaces. A <constant>NETDEV_REGISTER</constant> message is sent to the netdev notifier
   chain. 0 is returned on success. A negative errno code is returned
   on a failure to set up the device, or if the name is a duplicate.
   </para><para>

   Callers must hold the rtnl semaphore. You may want
   <function>register_netdev</function> instead of this.
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
   The locking appears insufficient to guarantee two parallel registers
   will not get the same name.
</para>
</refsect1>
</refentry>

<refentry id="API-register-netdev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_netdev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_netdev</refname>
 <refpurpose>
     register a network device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_netdev </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Take a completed network device structure and add it to the kernel
   interfaces. A <constant>NETDEV_REGISTER</constant> message is sent to the netdev notifier
   chain. 0 is returned on success. A negative errno code is returned
   on a failure to set up the device, or if the name is a duplicate.
   </para><para>

   This is a wrapper around register_netdevice that takes the rtnl semaphore
   and expands the device name if you passed a format string to
   alloc_netdev.
</para>
</refsect1>
</refentry>

<refentry id="API-alloc-netdev-mq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>alloc_netdev_mq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>alloc_netdev_mq</refname>
 <refpurpose>
     allocate network device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct net_device * <function>alloc_netdev_mq </function></funcdef>
   <paramdef>int <parameter>sizeof_priv</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>void (*<parameter>setup</parameter>)
     <funcparams>struct net_device *</funcparams></paramdef>
   <paramdef>unsigned int <parameter>queue_count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sizeof_priv</parameter></term>
   <listitem>
    <para>
     size of private data to allocate space for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     device name format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>setup</parameter></term>
   <listitem>
    <para>
     callback to initialize device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>queue_count</parameter></term>
   <listitem>
    <para>
     the number of subqueues to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates a struct net_device with private data area for driver use
   and performs basic initialization.  Also allocates subquue structs
   for each queue on the device at the end of the netdevice.
</para>
</refsect1>
</refentry>

<refentry id="API-free-netdev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>free_netdev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>free_netdev</refname>
 <refpurpose>
     free network device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>free_netdev </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function does the last stage of destroying an allocated device
   interface. The reference to the device object is released.
   If this is the last reference then it will be freed.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-netdevice">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_netdevice</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_netdevice</refname>
 <refpurpose>
     remove device from the kernel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_netdevice </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function shuts down a device interface and removes it
   from the kernel tables. On success 0 is returned, on a failure
   a negative errno code is returned.
   </para><para>

   Callers must hold the rtnl semaphore.  You may want
   <function>unregister_netdev</function> instead of this.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-netdev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_netdev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_netdev</refname>
 <refpurpose>
     remove device from the kernel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_netdev </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function shuts down a device interface and removes it
   from the kernel tables. On success 0 is returned, on a failure
   a negative errno code is returned.
   </para><para>

   This is just a wrapper for unregister_netdevice that takes
   the rtnl semaphore.  In general you want to use this and not
   unregister_netdevice.
</para>
</refsect1>
</refentry>

<refentry id="API-netdev-compute-features">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>netdev_compute_features</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>netdev_compute_features</refname>
 <refpurpose>
     compute conjunction of two feature sets
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>netdev_compute_features </function></funcdef>
   <paramdef>unsigned long <parameter>all</parameter></paramdef>
   <paramdef>unsigned long <parameter>one</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>all</parameter></term>
   <listitem>
    <para>
     first feature set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>one</parameter></term>
   <listitem>
    <para>
     second feature set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Computes a new feature set after adding a device with feature set
   <parameter>one</parameter> to the master device with current feature set <parameter>all</parameter>.  Returns
   the new feature set.
</para>
</refsect1>
</refentry>

<!-- net/ethernet/eth.c -->
<refentry id="API-eth-type-trans">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>eth_type_trans</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>eth_type_trans</refname>
 <refpurpose>
  determine the packet's protocol ID.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__be16 <function>eth_type_trans </function></funcdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     received socket data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     receiving network device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The rule here is that we
   assume 802.3 if the type field is short enough to be a length.
   This is normal practice and works for any 'now in use' protocol.
</para>
</refsect1>
</refentry>

<refentry id="API-ether-setup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ether_setup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ether_setup</refname>
 <refpurpose>
     setup Ethernet network device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>ether_setup </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     network device
     Fill in the fields of the device structure with Ethernet-generic values.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-alloc-etherdev-mq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>alloc_etherdev_mq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>alloc_etherdev_mq</refname>
 <refpurpose>
     Allocates and sets up an Ethernet device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct net_device * <function>alloc_etherdev_mq </function></funcdef>
   <paramdef>int <parameter>sizeof_priv</parameter></paramdef>
   <paramdef>unsigned int <parameter>queue_count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sizeof_priv</parameter></term>
   <listitem>
    <para>
     Size of additional driver-private structure to be allocated
     for this Ethernet device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>queue_count</parameter></term>
   <listitem>
    <para>
     The number of queues this device has.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Fill in the fields of the device structure with Ethernet-generic
   values. Basically does everything except registering the device.
   </para><para>

   Constructs a new net device, complete with a private data area of
   size (sizeof_priv).  A 32-byte (not bit) alignment is enforced for
   this private data area.
</para>
</refsect1>
</refentry>

<!-- include/linux/etherdevice.h -->
<refentry id="API-is-zero-ether-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>is_zero_ether_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>is_zero_ether_addr</refname>
 <refpurpose>
  Determine if give Ethernet address is all zeros.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>is_zero_ether_addr </function></funcdef>
   <paramdef>const u8 * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Pointer to a six-byte array containing the Ethernet address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return true if the address is all zeroes.
</para>
</refsect1>
</refentry>

<refentry id="API-is-multicast-ether-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>is_multicast_ether_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>is_multicast_ether_addr</refname>
 <refpurpose>
     Determine if the Ethernet address is a multicast.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>is_multicast_ether_addr </function></funcdef>
   <paramdef>const u8 * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Pointer to a six-byte array containing the Ethernet address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return true if the address is a multicast address.
   By definition the broadcast address is also a multicast address.
</para>
</refsect1>
</refentry>

<refentry id="API-is-local-ether-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>is_local_ether_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>is_local_ether_addr</refname>
 <refpurpose>
     Determine if the Ethernet address is locally-assigned
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>is_local_ether_addr </function></funcdef>
   <paramdef>const u8 * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Pointer to a six-byte array containing the Ethernet address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return true if the address is a local address.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return true if the address is a local address.
</para>
</refsect1>
</refentry>

<refentry id="API-is-broadcast-ether-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>is_broadcast_ether_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>is_broadcast_ether_addr</refname>
 <refpurpose>
     Determine if the Ethernet address is broadcast
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>is_broadcast_ether_addr </function></funcdef>
   <paramdef>const u8 * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Pointer to a six-byte array containing the Ethernet address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return true if the address is the broadcast address.
</para>
</refsect1>
</refentry>

<refentry id="API-is-valid-ether-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>is_valid_ether_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>is_valid_ether_addr</refname>
 <refpurpose>
     Determine if the given Ethernet address is valid
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>is_valid_ether_addr </function></funcdef>
   <paramdef>const u8 * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Pointer to a six-byte array containing the Ethernet address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check that the Ethernet address (MAC) is not 00:00:00:00:00:00, is not
   a multicast address, and is not FF:FF:FF:FF:FF:FF.
   </para><para>

   Return true if the address is valid.
</para>
</refsect1>
</refentry>

<refentry id="API-random-ether-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>random_ether_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>random_ether_addr</refname>
 <refpurpose>
     Generate software assigned random Ethernet address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>random_ether_addr </function></funcdef>
   <paramdef>u8 * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     Pointer to a six-byte array containing the Ethernet address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Generate a random Ethernet address (MAC) that is not multicast
   and has the local assigned bit set.
</para>
</refsect1>
</refentry>

<refentry id="API-compare-ether-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>compare_ether_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>compare_ether_addr</refname>
 <refpurpose>
     Compare two Ethernet addresses
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned <function>compare_ether_addr </function></funcdef>
   <paramdef>const u8 * <parameter>addr1</parameter></paramdef>
   <paramdef>const u8 * <parameter>addr2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>addr1</parameter></term>
   <listitem>
    <para>
     Pointer to a six-byte array containing the Ethernet address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr2</parameter></term>
   <listitem>
    <para>
     Pointer other six-byte array containing the Ethernet address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Compare two ethernet addresses, returns 0 if equal
</para>
</refsect1>
</refentry>

<!-- drivers/net/phy/phy.c -->
<refentry id="API-phy-print-status">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_print_status</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_print_status</refname>
 <refpurpose>
  Convenience function to print out the current phy status
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_print_status </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     the phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-phy-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_read</refname>
 <refpurpose>
     Convenience function for reading a given PHY register
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_read </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
   <paramdef>u16 <parameter>regnum</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     the phy_device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>regnum</parameter></term>
   <listitem>
    <para>
     register number to read
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   MUST NOT be called from interrupt context,
   because the bus read/write functions may wait for an interrupt
   to conclude the operation.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_write</refname>
 <refpurpose>
     Convenience function for writing a given PHY register
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_write </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
   <paramdef>u16 <parameter>regnum</parameter></paramdef>
   <paramdef>u16 <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     the phy_device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>regnum</parameter></term>
   <listitem>
    <para>
     register number to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     value to write to <parameter>regnum</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   MUST NOT be called from interrupt context,
   because the bus read/write functions may wait for an interrupt
   to conclude the operation.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-sanitize-settings">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_sanitize_settings</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_sanitize_settings</refname>
 <refpurpose>
     make sure the PHY is set to supported speed and duplex
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_sanitize_settings </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     the target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Make sure the PHY is set to supported speeds and
   duplexes.  Drop down by one in this order:  1000/FULL,
   1000/HALF, 100/FULL, 100/HALF, 10/FULL, 10/HALF.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-ethtool-sset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_ethtool_sset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_ethtool_sset</refname>
 <refpurpose>
     generic ethtool sset function, handles all the details
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_ethtool_sset </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
   <paramdef>struct ethtool_cmd * <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     ethtool_cmd
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>A few notes about parameter checking</title>
<para>
   - We don't set port or transceiver, so we don't care what they
   were set to.
   - <function>phy_start_aneg</function> will make sure forced settings are sane, and
   choose the next best ones from the ones selected, so we don't
   care if ethtool tries to give us bad values.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-start-aneg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_start_aneg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_start_aneg</refname>
 <refpurpose>
     start auto-negotiation for this PHY device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_start_aneg </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     the phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sanitizes the settings (if we're not autonegotiating
   them), and then calls the driver's config_aneg function.
   If the PHYCONTROL Layer is operating, we change the state to
   reflect the beginning of Auto-negotiation or forcing.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-enable-interrupts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_enable_interrupts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_enable_interrupts</refname>
 <refpurpose>
     Enable the interrupts from the PHY side
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_enable_interrupts </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-phy-disable-interrupts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_disable_interrupts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_disable_interrupts</refname>
 <refpurpose>
     Disable the PHY interrupts from the PHY side
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_disable_interrupts </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-phy-start-interrupts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_start_interrupts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_start_interrupts</refname>
 <refpurpose>
     request and enable interrupts for a PHY device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_start_interrupts </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Request the interrupt for the given PHY.
   If this fails, then we set irq to PHY_POLL.
   Otherwise, we enable the interrupts in the PHY.
   This should only be called with a valid IRQ number.
   Returns 0 on success or &lt; 0 on error.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-stop-interrupts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_stop_interrupts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_stop_interrupts</refname>
 <refpurpose>
     disable interrupts from a PHY device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_stop_interrupts </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-phy-stop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_stop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_stop</refname>
 <refpurpose>
     Bring down the PHY link, and stop checking the status
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_stop </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-phy-start">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_start</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_start</refname>
 <refpurpose>
     start or restart a PHY device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_start </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Indicates the attached device's readiness to
   handle PHY-related work.  Used during startup to start the
   PHY, and after a call to <function>phy_stop</function> to resume operation.
   Also used to indicate the MDIO bus has cleared an error
   condition.
</para>
</refsect1>
</refentry>

<!-- drivers/net/phy/phy.c -->
<refentry id="API-phy-clear-interrupt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_clear_interrupt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_clear_interrupt</refname>
 <refpurpose>
  Ack the phy device's interrupt
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_clear_interrupt </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     the phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the <parameter>phydev</parameter> driver has an ack_interrupt function, call it to
   ack and clear the phy device's interrupt.
   </para><para>

   Returns 0 on success on &lt; 0 on error.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-config-interrupt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_config_interrupt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_config_interrupt</refname>
 <refpurpose>
     configure the PHY device for the requested interrupts
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_config_interrupt </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
   <paramdef>u32 <parameter>interrupts</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     the phy_device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>interrupts</parameter></term>
   <listitem>
    <para>
     interrupt flags to configure for this <parameter>phydev</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success on &lt; 0 on error.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-aneg-done">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_aneg_done</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_aneg_done</refname>
 <refpurpose>
     return auto-negotiation status
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_aneg_done </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reads the status register and returns 0 either if
   auto-negotiation is incomplete, or if there was an error.
   Returns BMSR_ANEGCOMPLETE if auto-negotiation is done.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-find-setting">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_find_setting</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_find_setting</refname>
 <refpurpose>
     find a PHY settings array entry that matches speed &amp; duplex
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_find_setting </function></funcdef>
   <paramdef>int <parameter>speed</parameter></paramdef>
   <paramdef>int <parameter>duplex</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>speed</parameter></term>
   <listitem>
    <para>
     speed to match
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>duplex</parameter></term>
   <listitem>
    <para>
     duplex to match
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Searches the settings array for the setting which
   matches the desired speed and duplex, and returns the index
   of that setting.  Returns the index of the last setting if
   none of the others match.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-find-valid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_find_valid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_find_valid</refname>
 <refpurpose>
     find a PHY setting that matches the requested features mask
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_find_valid </function></funcdef>
   <paramdef>int <parameter>idx</parameter></paramdef>
   <paramdef>u32 <parameter>features</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>idx</parameter></term>
   <listitem>
    <para>
     The first index in settings[] to search
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>features</parameter></term>
   <listitem>
    <para>
     A mask of the valid settings
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the index of the first valid setting less
   than or equal to the one pointed to by idx, as determined by
   the mask in features.  Returns the index of the last setting
   if nothing else matches.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-mii-ioctl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_mii_ioctl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_mii_ioctl</refname>
 <refpurpose>
     generic PHY MII ioctl interface
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_mii_ioctl </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
   <paramdef>struct mii_ioctl_data * <parameter>mii_data</parameter></paramdef>
   <paramdef>int <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     the phy_device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mii_data</parameter></term>
   <listitem>
    <para>
     MII ioctl data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     ioctl cmd to execute
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that this function is currently incompatible with the
   PHYCONTROL layer.  It changes registers without regard to
   current state.  Use at own risk.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-start-machine">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_start_machine</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_start_machine</refname>
 <refpurpose>
     start PHY state machine tracking
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_start_machine </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
   <paramdef>void (*<parameter>handler</parameter>)
     <funcparams>struct net_device *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     the phy_device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
     callback function for state change notifications
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The PHY infrastructure can run a state machine
   which tracks whether the PHY is starting up, negotiating,
   etc.  This function starts the timer which tracks the state
   of the PHY.  If you want to be notified when the state changes,
   pass in the callback <parameter>handler</parameter>, otherwise, pass NULL.  If you
   want to maintain your own state machine, do not call this
   function.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-stop-machine">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_stop_machine</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_stop_machine</refname>
 <refpurpose>
     stop the PHY state machine tracking
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_stop_machine </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Stops the state machine timer, sets the state to UP
   (unless it wasn't up yet). This function must be called BEFORE
   phy_detach.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-force-reduction">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_force_reduction</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_force_reduction</refname>
 <refpurpose>
     reduce PHY speed/duplex settings by one step
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_force_reduction </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reduces the speed/duplex settings by one notch,
   in this order--
   1000/FULL, 1000/HALF, 100/FULL, 100/HALF, 10/FULL, 10/HALF.
   The function bottoms out at 10/HALF.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-error">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_error</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_error</refname>
 <refpurpose>
     enter HALTED state for this PHY device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_error </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Moves the PHY to the HALTED state in response to a read
   or write error, and tells the controller the link is down.
   Must not be called from interrupt context, or while the
   phydev-&gt;lock is held.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-interrupt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_interrupt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_interrupt</refname>
 <refpurpose>
     PHY interrupt handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>irqreturn_t <function>phy_interrupt </function></funcdef>
   <paramdef>int <parameter>irq</parameter></paramdef>
   <paramdef>void * <parameter>phy_dat</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>phy_dat</parameter></term>
   <listitem>
    <para>
     phy_device pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When a PHY interrupt occurs, the handler disables
   interrupts, and schedules a work task to clear the interrupt.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-change">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_change</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_change</refname>
 <refpurpose>
     Scheduled by the phy_interrupt/timer to handle PHY changes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_change </function></funcdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     work_struct that describes the work to be done
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/net/phy/phy_device.c -->
<refentry id="API-phy-connect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_connect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_connect</refname>
 <refpurpose>
  connect an ethernet device to a PHY device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct phy_device * <function>phy_connect </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>const char * <parameter>phy_id</parameter></paramdef>
   <paramdef>void (*<parameter>handler</parameter>)
     <funcparams>struct net_device *</funcparams></paramdef>
   <paramdef>u32 <parameter>flags</parameter></paramdef>
   <paramdef>phy_interface_t <parameter>interface</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the network device to connect
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>phy_id</parameter></term>
   <listitem>
    <para>
     the PHY device to connect
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
     callback function for state change notifications
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     PHY device's dev_flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>interface</parameter></term>
   <listitem>
    <para>
     PHY device's interface
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Convenience function for connecting ethernet
   devices to PHY devices.  The default behavior is for
   the PHY infrastructure to handle everything, and only notify
   the connected driver when the link status changes.  If you
   don't want, or can't use the provided functionality, you may
   choose to call only the subset of functions which provide
   the desired functionality.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-disconnect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_disconnect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_disconnect</refname>
 <refpurpose>
     disable interrupts, stop state machine, and detach a PHY device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_disconnect </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-phy-attach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_attach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_attach</refname>
 <refpurpose>
     attach a network device to a particular PHY device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct phy_device * <function>phy_attach </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>const char * <parameter>phy_id</parameter></paramdef>
   <paramdef>u32 <parameter>flags</parameter></paramdef>
   <paramdef>phy_interface_t <parameter>interface</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     network device to attach
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>phy_id</parameter></term>
   <listitem>
    <para>
     PHY device to attach
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     PHY device's dev_flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>interface</parameter></term>
   <listitem>
    <para>
     PHY device's interface
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called by drivers to attach to a particular PHY
   device. The phy_device is found, and properly hooked up
   to the phy_driver.  If no driver is attached, then the
   genphy_driver is used.  The phy_device is given a ptr to
   the attaching device, and given a callback for link status
   change.  The phy_device is returned to the attaching driver.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-detach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_detach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_detach</refname>
 <refpurpose>
     detach a PHY device from its network device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_detach </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-genphy-config-advert">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>genphy_config_advert</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>genphy_config_advert</refname>
 <refpurpose>
     sanitize and advertise auto-negotation parameters
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>genphy_config_advert </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Writes MII_ADVERTISE with the appropriate values,
   after sanitizing the values to make sure we only advertise
   what is supported.
</para>
</refsect1>
</refentry>

<refentry id="API-genphy-config-aneg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>genphy_config_aneg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>genphy_config_aneg</refname>
 <refpurpose>
     restart auto-negotiation or write BMCR
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>genphy_config_aneg </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If auto-negotiation is enabled, we configure the
   advertising, and then restart auto-negotiation.  If it is not
   enabled, then we write the BMCR.
</para>
</refsect1>
</refentry>

<refentry id="API-genphy-update-link">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>genphy_update_link</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>genphy_update_link</refname>
 <refpurpose>
     update link status in <parameter>phydev</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>genphy_update_link </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Update the value in phydev-&gt;link to reflect the
   current link value.  In order to do this, we need to read
   the status register twice, keeping the second value.
</para>
</refsect1>
</refentry>

<refentry id="API-genphy-read-status">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>genphy_read_status</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>genphy_read_status</refname>
 <refpurpose>
     check the link status and update current link state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>genphy_read_status </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check the link, then figure out the current state
   by comparing what we advertise with what the link partner
   advertises.  Start by checking the gigabit possibilities,
   then move on to 10/100.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-driver-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_driver_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_driver_register</refname>
 <refpurpose>
     register a phy_driver with the PHY layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_driver_register </function></funcdef>
   <paramdef>struct phy_driver * <parameter>new_driver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>new_driver</parameter></term>
   <listitem>
    <para>
     new phy_driver to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/net/phy/phy_device.c -->
<refentry id="API-get-phy-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_phy_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_phy_device</refname>
 <refpurpose>
  reads the specified PHY device and returns its <parameter>phy_device</parameter> struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct phy_device * <function>get_phy_device </function></funcdef>
   <paramdef>struct mii_bus * <parameter>bus</parameter></paramdef>
   <paramdef>int <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     the target MII bus
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     PHY address on the MII bus
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reads the ID registers of the PHY at <parameter>addr</parameter> on the
   <parameter>bus</parameter>, then allocates and returns the phy_device to represent it.
</para>
</refsect1>
</refentry>

<refentry id="API-phy-prepare-link">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_prepare_link</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_prepare_link</refname>
 <refpurpose>
     prepares the PHY layer to monitor link status
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>phy_prepare_link </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
   <paramdef>void (*<parameter>handler</parameter>)
     <funcparams>struct net_device *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
     callback function for link status change notifications
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Tells the PHY infrastructure to handle the
   gory details on monitoring link status (whether through
   polling or an interrupt), and to call back to the
   connected device driver when the link status changes.
   If you want to monitor your own link state, don't call
   this function.
</para>
</refsect1>
</refentry>

<refentry id="API-genphy-setup-forced">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>genphy_setup_forced</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>genphy_setup_forced</refname>
 <refpurpose>
     configures/forces speed/duplex from <parameter>phydev</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>genphy_setup_forced </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Configures MII_BMCR to force speed/duplex
   to the values in phydev. Assumes that the values are valid.
   Please see <function>phy_sanitize_settings</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-genphy-restart-aneg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>genphy_restart_aneg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>genphy_restart_aneg</refname>
 <refpurpose>
     Enable and Restart Autonegotiation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>genphy_restart_aneg </function></funcdef>
   <paramdef>struct phy_device * <parameter>phydev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>phydev</parameter></term>
   <listitem>
    <para>
     target phy_device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-phy-probe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>phy_probe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>phy_probe</refname>
 <refpurpose>
     probe and init a PHY device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>phy_probe </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to probe and init
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Take care of setting up the phy_device structure,
   set the state to READY (the driver's init function should
   set it to STARTING if needed).
</para>
</refsect1>
</refentry>

<!-- drivers/net/phy/mdio_bus.c -->
<refentry id="API-mdiobus-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mdiobus_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mdiobus_register</refname>
 <refpurpose>
  bring up all the PHYs on a given bus and attach them to bus
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mdiobus_register </function></funcdef>
   <paramdef>struct mii_bus * <parameter>bus</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus</parameter></term>
   <listitem>
    <para>
     target mii_bus
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called by a bus driver to bring up all the PHYs
   on a given bus, and attach them to the bus.
   </para><para>

   Returns 0 on success or &lt; 0 on error.
</para>
</refsect1>
</refentry>

<!-- drivers/net/phy/mdio_bus.c -->
<refentry id="API-mdio-bus-match">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mdio_bus_match</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mdio_bus_match</refname>
 <refpurpose>
  determine if given PHY driver supports the given PHY device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mdio_bus_match </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct device_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     target PHY device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     given PHY driver
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a PHY device, and a PHY driver, return 1 if
   the driver supports the device.  Otherwise, return 0.
</para>
</refsect1>
</refentry>

<!-- FIXME: Removed for now since no structured comments in source
X!Enet/core/wireless.c
-->
     </sect1>
     <sect1><title>Synchronous PPP</title>
<!-- drivers/net/wan/syncppp.c -->
<refentry id="API-sppp-close">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sppp_close</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sppp_close</refname>
 <refpurpose>
  close down a synchronous PPP or Cisco HDLC link
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sppp_close </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     The network device to drop the link of
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This drops the logical interface to the channel. It is not
   done politely as we assume we will also be dropping DTR. Any
   timeouts are killed.
</para>
</refsect1>
</refentry>

<refentry id="API-sppp-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sppp_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sppp_open</refname>
 <refpurpose>
     open a synchronous PPP or Cisco HDLC link
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sppp_open </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Network device to activate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Close down any existing synchronous session and commence
   from scratch. In the PPP case this means negotiating LCP/IPCP
   and friends, while for Cisco HDLC we simply need to start sending
   keepalives
</para>
</refsect1>
</refentry>

<refentry id="API-sppp-reopen">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sppp_reopen</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sppp_reopen</refname>
 <refpurpose>
     notify of physical link loss
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sppp_reopen </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device that lost the link
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function informs the synchronous protocol code that
   the underlying link died (for example a carrier drop on X.21)
   </para><para>

   We increment the magic numbers to ensure that if the other end
   failed to notice we will correctly start a new session. It happens
   do to the nature of telco circuits is that you can lose carrier on
   one endonly.
   </para><para>

   Having done this we go back to negotiating. This function may
   be called from an interrupt context.
</para>
</refsect1>
</refentry>

<refentry id="API-sppp-do-ioctl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sppp_do_ioctl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sppp_do_ioctl</refname>
 <refpurpose>
     Ioctl handler for ppp/hdlc
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sppp_do_ioctl </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct ifreq * <parameter>ifr</parameter></paramdef>
   <paramdef>int <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device subject to ioctl
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ifr</parameter></term>
   <listitem>
    <para>
     Interface request block from the user
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     Command that is being issued
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function handles the ioctls that may be issued by the user
   to control the settings of a PPP/HDLC link. It does both busy
   and security checks. This function is intended to be wrapped by
   callers who wish to add additional ioctl calls of their own.
</para>
</refsect1>
</refentry>

<refentry id="API-sppp-attach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sppp_attach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sppp_attach</refname>
 <refpurpose>
     attach synchronous PPP/HDLC to a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sppp_attach </function></funcdef>
   <paramdef>struct ppp_device * <parameter>pd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pd</parameter></term>
   <listitem>
    <para>
     PPP device to initialise
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This initialises the PPP/HDLC support on an interface. At the
   time of calling the dev element must point to the network device
   that this interface is attached to. The interface should not yet
   be registered. 
</para>
</refsect1>
</refentry>

<refentry id="API-sppp-detach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sppp_detach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sppp_detach</refname>
 <refpurpose>
     release PPP resources from a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sppp_detach </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Network device to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Stop and free up any PPP/HDLC resources used by this
   interface. This must be called before the device is
   freed.
</para>
</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_module</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     printf style format string for the name of the module
    </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>call_usermodehelper_setup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
  </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>
 </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>
</refsect1>
</refentry>

<refentry id="API-call-usermodehelper-setkeys">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>call_usermodehelper_setkeys</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>call_usermodehelper_setkeys</refname>
 <refpurpose>
     set the session keys for usermode helper
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>call_usermodehelper_setkeys </function></funcdef>
   <paramdef>struct subprocess_info * <parameter>info</parameter></paramdef>
   <paramdef>struct key * <parameter>session_keyring</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     a subprocess_info returned by call_usermodehelper_setup
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>session_keyring</parameter></term>
   <listitem>
    <para>
     the session keyring for the process
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-call-usermodehelper-setcleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>call_usermodehelper_setcleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>call_usermodehelper_setcleanup</refname>
 <refpurpose>
     set a cleanup function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>call_usermodehelper_setcleanup </function></funcdef>
   <paramdef>struct subprocess_info * <parameter>info</parameter></paramdef>
   <paramdef>void (*<parameter>cleanup</parameter>)
     <funcparams>char **argv, char **envp</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     a subprocess_info returned by call_usermodehelper_setup
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cleanup</parameter></term>
   <listitem>
    <para>
     a cleanup function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The cleanup function is just befor 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-stdinpipe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>call_usermodehelper_stdinpipe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>call_usermodehelper_stdinpipe</refname>
 <refpurpose>
     set up a pipe to be used for stdin
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>call_usermodehelper_stdinpipe </function></funcdef>
   <paramdef>struct subprocess_info * <parameter>sub_info</parameter></paramdef>
   <paramdef>struct file ** <parameter>filp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sub_info</parameter></term>
   <listitem>
    <para>
     a subprocess_info returned by call_usermodehelper_setup
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     set to the write-end of a pipe
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This constructs a pipe, and sets the read end to be the stdin of the
   subprocess, and returns the write-end in *<parameter>filp</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-call-usermodehelper-exec">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>call_usermodehelper_exec</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>enum umh_wait <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 -1 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-pipe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>call_usermodehelper_pipe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>call_usermodehelper_pipe</refname>
 <refpurpose>
     call a usermode helper process with a pipe stdin
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>call_usermodehelper_pipe </function></funcdef>
   <paramdef>char * <parameter>path</parameter></paramdef>
   <paramdef>char ** <parameter>argv</parameter></paramdef>
   <paramdef>char ** <parameter>envp</parameter></paramdef>
   <paramdef>struct file ** <parameter>filp</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>filp</parameter></term>
   <listitem>
    <para>
     set to the write-end of a pipe
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a simple wrapper which executes a usermode-helper function
   with a pipe as stdin.  It is implemented entirely in terms of
   lower-level call_usermodehelper_* functions.
</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-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>synchronize_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-disable-irq-nosync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disable_irq_nosync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>disable_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-enable-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enable_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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.
</para>
</refsect1>
</refentry>

<refentry id="API-set-irq-wake">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>set_irq_wake</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>set_irq_wake</refname>
 <refpurpose>
     control irq power management wakeup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>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-free-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>free_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>free_irq</refname>
 <refpurpose>
     free an interrupt
 </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-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>request_irq</refname>
 <refpurpose>
     allocate an interrupt line
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>request_irq </function></funcdef>
   <paramdef>unsigned int <parameter>irq</parameter></paramdef>
   <paramdef>irq_handler_t <parameter>handler</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
    </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>

   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_DISABLED	Disable local interrupts while processing
   IRQF_SAMPLE_RANDOM	The interrupt can be used for entropy
</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_dma</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>free_dma</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-insert-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>insert_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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><para>

   This function is equivalent to request_resource 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>

<!-- kernel/resource.c -->
<refentry id="API-request-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>release_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>allocate_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>allocate_resource</refname>
 <refpurpose>
     allocate empty slot in the resource tree given range &amp; alignment
 </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>void (*<parameter>alignf</parameter>)
     <funcparams>void *, 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 size to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     maximum size 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>adjust_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__request_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
  </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>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API---check-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__check_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__check_region</refname>
 <refpurpose>
     check if a resource region is busy or free
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__check_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>
   Returns 0 if the region is free at the moment it is checked,
   returns <constant>-EBUSY</constant> if the region is busy.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   This function is deprecated because its use is racy.
   Even if it returns 0, a subsequent call to <function>request_region</function>
   may fail because another driver etc. just allocated the region.
   Do NOT use it.  It will be removed from the kernel.
</para>
</refsect1>
</refentry>

<refentry id="API---release-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__release_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

     </sect1>

     <sect1><title>MTRR Handling</title>
<!-- arch/i386/kernel/cpu/mtrr/main.c -->
<refentry id="API-mtrr-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mtrr_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>char <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mtrr_del</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

     </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_bus_max_busnr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_bus_find_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-ext-capability">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_ext_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_next_ht_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_ht_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_parent_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 or where
   it should be allocated from.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-restore-bars">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_restore_bars</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_restore_bars</refname>
 <refpurpose>
     restore a devices BAR values (e.g. after wake-up)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_restore_bars </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 have its BARs restored
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Restore the BAR values for a given device, so as to make it
   accessible by its driver.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-set-power-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_set_power_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 be suspended
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     PCI power state (D0, D1, D2, D3hot, D3cold) we're entering
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Transition a device to a new power state, using the Power Management 
   Capabilities in the device's config space.
</para>
</refsect1>
<refsect1>
<title>RETURN VALUE</title>
<para>
   </para><para>

   -EINVAL if trying to enter a lower state than we're already in.
   0 if we're already in the requested state.
   -EIO if device does not support PCI PM.
   0 if we can successfully change the power state.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-choose-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_choose_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_save_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_restore_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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-reenable-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_reenable_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-bars">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_device_bars</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_enable_device_bars</refname>
 <refpurpose>
     Initialize some of a device for use
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_enable_device_bars </function></funcdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>bars</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>
  <varlistentry>
   <term><parameter>bars</parameter></term>
   <listitem>
    <para>
     bitmask of BAR's that must be configured
    </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 selected I/O and 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcim_enable_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcim_pin_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_disable_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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_device_enable</function> have called <function>pci_device_disable</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-set-pcie-reset-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_set_pcie_reset_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 PCI-E 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-enable-wake">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_wake</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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>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.  Depending on the platform, devices
   supporting the standard PCI PME# signal may require such platform hooks;
   they always update bits in config space to allow PME# generation.
   </para><para>

   -EIO is returned if the device can't ever be a wakeup event source.
   -EINVAL is returned if the device can't generate wakeup events from
   the specified PCI state.  Returns zero if the operation is successful.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-release-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_release_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_request_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_request_region</refname>
 <refpurpose>
     Reserved 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> 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>
</refsect1>
</refentry>

<refentry id="API-pci-release-selected-regions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_release_selected_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_request_selected_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_release_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_request_regions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-set-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_set_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-set-mwi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_set_mwi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_try_set_mwi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_clear_mwi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_intx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-pcix-get-max-mmrbc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcix_get_max_mmrbc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcix_get_mmrbc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcix_set_mmrbc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcie_get_readrq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pcie_set_readrq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 read byte count
</para>
</refsect1>
</refentry>

<refentry id="API-pci-select-bars">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_select_bars</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-match-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_match_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-match-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_match_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_match_device</refname>
 <refpurpose>
     Tell if a PCI device structure has a matching PCI device id structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct pci_device_id * <function>pci_match_device </function></funcdef>
   <paramdef>struct pci_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     the PCI driver to match against
    </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>
</refsect1>
</refentry>

<refentry id="API---pci-register-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__pci_register_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_unregister_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_dev_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_dev_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_dev_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-remove-bus-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_remove_bus_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_remove_bus_device</refname>
 <refpurpose>
  remove a PCI device and any children
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_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>

<refentry id="API-pci-remove-behind-bridge">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_remove_behind_bridge</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_remove_behind_bridge</refname>
 <refpurpose>
     remove all devices behind a PCI bridge
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_remove_behind_bridge </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 bridge device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove all devices on the bus, except for the parent bridge.
   This also removes any child buses, and any devices they may
   contain in a depth-first manner.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-stop-bus-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_stop_bus_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_stop_bus_device</refname>
 <refpurpose>
     stop a PCI device and any children
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_stop_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 stop
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Stop a PCI device (detach the driver, remove from the global list
   and so on). This also stop any subordinate buses and children in a
   depth-first manner.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/pci-acpi.c -->
<refentry id="API-pci-osc-support-set">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_osc_support_set</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_osc_support_set</refname>
 <refpurpose>
  register OS support to Firmware
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>acpi_status <function>pci_osc_support_set </function></funcdef>
   <paramdef>u32 <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     OS support bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Update OS support fields and doing a _OSC Query to obtain an update
   from Firmware on supported control bits.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-osc-control-set">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_osc_control_set</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_osc_control_set</refname>
 <refpurpose>
     commit requested control to Firmware
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>acpi_status <function>pci_osc_control_set </function></funcdef>
   <paramdef>acpi_handle <parameter>handle</parameter></paramdef>
   <paramdef>u32 <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     acpi_handle for the target ACPI object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     driver's requested control bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Attempt to take control from Firmware on requested control bits.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/search.c -->
<refentry id="API-pci-find-bus">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_bus</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_next_bus</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 busses.  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-find-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_find_slot</refname>
 <refpurpose>
     locate PCI device from a given PCI slot
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_dev * <function>pci_find_slot </function></funcdef>
   <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>bus</parameter></term>
   <listitem>
    <para>
     number of 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 system global list of PCI devices.  If the device
   is found, a pointer to its data structure is returned.  If no 
   device is found, <constant>NULL</constant> is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-get-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_get_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-bus-and-slot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_get_bus_and_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_get_bus_and_slot</refname>
 <refpurpose>
     locate PCI device from a given PCI bus &amp; slot
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pci_dev * <function>pci_get_bus_and_slot </function></funcdef>
   <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>bus</parameter></term>
   <listitem>
    <para>
     number of 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>Note</title>
<para>
   the bus/slot search is limited to PCI domain (segment) 0.
   </para><para>

   Given a PCI bus and slot/function number, the desired PCI device
   is located in system global list of PCI devices.  If the device
   is found, a pointer to its data structure is returned.  If no
   device is found, <constant>NULL</constant> is returned. The returned device has its
   reference count bumped by one.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-find-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_find_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_find_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_find_device </function></funcdef>
   <paramdef>unsigned int <parameter>vendor</parameter></paramdef>
   <paramdef>unsigned int <parameter>device</parameter></paramdef>
   <paramdef>const 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>, 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.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   Do not use this function any more; use <function>pci_get_device</function> instead, as
   the PCI device returned by this function can disappear at any moment in
   time.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-get-subsys">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_get_subsys</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_get_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-device-reverse">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_get_device_reverse</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_get_device_reverse</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_reverse </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 in the reverse order of
   pci_get_device.
   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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_get_class</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_dev_present</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-enable-msi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_msi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_enable_msi</refname>
 <refpurpose>
  configure device's MSI capability structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pci_enable_msi </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 device function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Setup the MSI capability structure of device function with
   a single MSI irq upon its software driver call to request for
   MSI mode enabled on its hardware device function. A return of zero
   indicates the successful setup of an entry zero with the new MSI
   irq or non-zero for otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-pci-enable-msix">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_enable_msix</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 available. Driver should use the returned value to re-send
   its request.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/bus.c -->
<refentry id="API-pci-bus-alloc-resource">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_bus_alloc_resource</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 int <parameter>type_mask</parameter></paramdef>
   <paramdef>void (*<parameter>alignf</parameter>)
     <funcparams>void *, 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_bus_add_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_bus_add_device</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <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 a single pci device to the global
   device list and adds sysfs and procfs entries
</para>
</refsect1>
</refentry>

<refentry id="API-pci-bus-add-devices">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_bus_add_devices</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_bus_add_devices</refname>
 <refpurpose>
     insert newly discovered PCI devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_bus_add_devices </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>
     bus to check for new devices
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add newly discovered PCI devices (which are on the bus-&gt;devices
   list) to the global PCI device list, add the sysfs and procfs
   entries.  Where a bridge is found, add the discovered bus to
   the parents list of child buses, and recurse (breadth-first
   to be compatible with 2.4)
   </para><para>

   Call hotplug for each new devices.
</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_scan_slot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 have an empty dev-&gt;global_list head.
</para>
</refsect1>
</refentry>

<!-- drivers/pci/rom.c -->
<refentry id="API-pci-map-rom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_map_rom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>Description</title>
<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-map-rom-copy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_map_rom_copy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_map_rom_copy</refname>
 <refpurpose>
     map a PCI ROM to kernel space, create a copy
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __iomem * <function>pci_map_rom_copy </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>Description</title>
<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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_unmap_rom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-remove-rom">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_remove_rom</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pci_remove_rom</refname>
 <refpurpose>
     disable the ROM and remove its sysfs attribute
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pci_remove_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>
     pointer to pci device struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove the rom file in sysfs and disable ROM decoding.
</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_hp_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>slot</parameter></term>
   <listitem>
    <para>
     pointer to the &amp;struct hotplug_slot to register
    </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_hp_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>slot</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>slot</parameter></term>
   <listitem>
    <para>
     pointer to the &amp;struct hotplug_slot 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pci_hp_change_slot_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 __must_check <function>pci_hp_change_slot_info </function></funcdef>
   <paramdef>struct hotplug_slot * <parameter>slot</parameter></paramdef>
   <paramdef>struct hotplug_slot_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>slot</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>
     <sect1><title>MCA Architecture</title>
	<sect2><title>MCA Device Functions</title>
           <para>
              Refer to the file arch/i386/kernel/mca.c for more information.
           </para>
<!-- FIXME: Removed for now since no structured comments in source
X!Earch/i386/kernel/mca.c
-->
	</sect2>
	<sect2><title>MCA Bus DMA</title>
<!-- include/asm-i386/mca_dma.h -->
<refentry id="API-mca-enable-dma">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mca_enable_dma</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mca_enable_dma</refname>
 <refpurpose>
  channel to enable DMA on
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mca_enable_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
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enable the MCA bus DMA on a channel. This can be called from
   IRQ context.
</para>
</refsect1>
</refentry>

<refentry id="API-mca-disable-dma">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mca_disable_dma</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mca_disable_dma</refname>
 <refpurpose>
     channel to disable DMA on
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mca_disable_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
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enable the MCA bus DMA on a channel. This can be called from
   IRQ context.
</para>
</refsect1>
</refentry>

<refentry id="API-mca-set-dma-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mca_set_dma_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mca_set_dma_addr</refname>
 <refpurpose>
     load a 24bit DMA address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mca_set_dma_addr </function></funcdef>
   <paramdef>unsigned int <parameter>dmanr</parameter></paramdef>
   <paramdef>unsigned int <parameter>a</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmanr</parameter></term>
   <listitem>
    <para>
     DMA channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>a</parameter></term>
   <listitem>
    <para>
     24bit bus address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Load the address register in the DMA controller. This has a 24bit
   limitation (16Mb). 
</para>
</refsect1>
</refentry>

<refentry id="API-mca-get-dma-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mca_get_dma_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mca_get_dma_addr</refname>
 <refpurpose>
     load a 24bit DMA address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>mca_get_dma_addr </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
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Read the address register in the DMA controller. This has a 24bit
   limitation (16Mb). The return is a bus address.
</para>
</refsect1>
</refentry>

<refentry id="API-mca-set-dma-count">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mca_set_dma_count</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mca_set_dma_count</refname>
 <refpurpose>
     load a 16bit transfer count
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mca_set_dma_count </function></funcdef>
   <paramdef>unsigned int <parameter>dmanr</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmanr</parameter></term>
   <listitem>
    <para>
     DMA channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     count
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set the DMA count for this channel. This can be up to 64Kbytes.
   Setting a count of zero will not do what you expect.
</para>
</refsect1>
</refentry>

<refentry id="API-mca-get-dma-residue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mca_get_dma_residue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mca_get_dma_residue</refname>
 <refpurpose>
     get the remaining bytes to transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>mca_get_dma_residue </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
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function returns the number of bytes left to transfer
   on this DMA channel.
</para>
</refsect1>
</refentry>

<refentry id="API-mca-set-dma-io">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mca_set_dma_io</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mca_set_dma_io</refname>
 <refpurpose>
     set the port for an I/O transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mca_set_dma_io </function></funcdef>
   <paramdef>unsigned int <parameter>dmanr</parameter></paramdef>
   <paramdef>unsigned int <parameter>io_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmanr</parameter></term>
   <listitem>
    <para>
     DMA channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>io_addr</parameter></term>
   <listitem>
    <para>
     an I/O port number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unlike the ISA bus DMA controllers the DMA on MCA bus can transfer
   with an I/O port target.
</para>
</refsect1>
</refentry>

<refentry id="API-mca-set-dma-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mca_set_dma_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mca_set_dma_mode</refname>
 <refpurpose>
     set the DMA mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mca_set_dma_mode </function></funcdef>
   <paramdef>unsigned int <parameter>dmanr</parameter></paramdef>
   <paramdef>unsigned int <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmanr</parameter></term>
   <listitem>
    <para>
     DMA channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode to set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The DMA controller supports several modes. The mode values you can
   set are-
   </para><para>

   <constant>MCA_DMA_MODE_READ</constant> when reading from the DMA device.
   </para><para>

   <constant>MCA_DMA_MODE_WRITE</constant> to writing to the DMA device.
   </para><para>

   <constant>MCA_DMA_MODE_IO</constant> to do DMA to or from an I/O port.
   </para><para>

   <constant>MCA_DMA_MODE_16</constant> to do 16bit transfers.
</para>
</refsect1>
</refentry>

	</sect2>
     </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_check_system</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>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-get-system-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_get_system_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmi_get_system_info</refname>
 <refpurpose>
     return DMI data value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_name_in_vendors</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmi_name_in_vendors</refname>
 <refpurpose>
     Check if string is anywhere in the DMI vendor information.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>dmi_name_in_vendors </function></funcdef>
   <paramdef>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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmi_find_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>dmi_find_device</refname>
 <refpurpose>
     find onboard device by type/name
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct dmi_device * <function>dmi_find_device </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>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>

     </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>edd_show_raw_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>edd_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>edd_dev_is_type</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>edd_get_pci_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>edd_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>edd_init</refname>
 <refpurpose>
     creates sysfs tree of EDD data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <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-register-security">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_security</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 is to allow 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.  A call to <function>unregister_security</function> should be
   done to remove this security_options structure from the kernel.
   </para><para>

   If there is already a security module registered with the kernel,
   an error will be returned.  Otherwise 0 is returned on success.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-security">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_security</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_security</refname>
 <refpurpose>
     unregisters a security framework with the kernel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>unregister_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 removes a struct security_operations variable that had
   previously been registered with a successful call to <function>register_security</function>.
   </para><para>

   If <parameter>ops</parameter> does not match the valued previously passed to <function>register_security</function>
   an error is returned.  Otherwise the default security options is set to the
   the dummy_security_ops structure, and 0 is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-mod-reg-security">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mod_reg_security</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mod_reg_security</refname>
 <refpurpose>
     allows security modules to be <quote>stacked</quote>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mod_reg_security </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct security_operations * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     a pointer to a string with the name of the security_options to be registered
    </para>
   </listitem>
  </varlistentry>
  <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 security modules to be stacked if the currently loaded
   security module allows this to happen.  It passes the <parameter>name</parameter> and <parameter>ops</parameter> to the
   register_security function of the currently loaded security module.
   </para><para>

   The return value depends on the currently loaded security module, with 0 as
   success.
</para>
</refsect1>
</refentry>

<refentry id="API-mod-unreg-security">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mod_unreg_security</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mod_unreg_security</refname>
 <refpurpose>
     allows a security module registered with <function>mod_reg_security</function> to be unloaded
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mod_unreg_security </function></funcdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct security_operations * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     a pointer to a string with the name of the security_options to be removed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     a pointer to the struct security_options that is to be removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function allows security modules that have been successfully registered
   with a call to <function>mod_reg_security</function> to be unloaded from the system.
   This calls the currently loaded security module's <function>unregister_security</function> call
   with the <parameter>name</parameter> and <parameter>ops</parameter> variables.
   </para><para>

   The return value depends on the currently loaded security module, with 0 as
   success.
</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_log_start</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_log_format</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_log_end</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
   The netlink_* functions cannot be called inside an irq context, 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_log</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

<!-- kernel/auditsc.c -->
<refentry id="API-audit-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_syscall_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>arch</parameter></paramdef>
   <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>arch</parameter></term>
   <listitem>
    <para>
     architecture type
    </para>
   </listitem>
  </varlistentry>
  <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_syscall_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>valid</parameter></paramdef>
   <paramdef>long <parameter>return_code</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>valid</parameter></term>
   <listitem>
    <para>
     success/failure flag
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>return_code</parameter></term>
   <listitem>
    <para>
     syscall return value
    </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 write 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-getname">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_getname</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>const char * <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_inode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>const char * <parameter>name</parameter></paramdef>
   <paramdef>const struct inode * <parameter>inode</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>inode</parameter></term>
   <listitem>
    <para>
     inode being audited
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called from fs/namei.c:<function>path_lookup</function>.
</para>
</refsect1>
</refentry>

<refentry id="API---audit-inode-child">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_inode_child</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_inode_child</refname>
 <refpurpose>
     collect inode info for created/removed objects
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__audit_inode_child </function></funcdef>
   <paramdef>const char * <parameter>dname</parameter></paramdef>
   <paramdef>const struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>const struct inode * <parameter>parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dname</parameter></term>
   <listitem>
    <para>
     inode's dentry name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     inode being audited
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     inode of dentry parent
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   For syscalls that create or remove filesystem objects, audit_inode
   can only collect information for the filesystem object's parent.
   This call updates the audit context with the child's information.
   Syscalls that create a new filesystem object must be hooked after
   the object is created.  Syscalls that remove a filesystem object
   must be hooked prior, in order to capture the target inode during
   unsuccessful attempts.
</para>
</refsect1>
</refentry>

<refentry id="API-auditsc-get-stamp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>auditsc_get_stamp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>void <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_set_loginuid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_set_loginuid</refname>
 <refpurpose>
     set a task's audit_context loginuid
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>audit_set_loginuid </function></funcdef>
   <paramdef>struct task_struct * <parameter>task</parameter></paramdef>
   <paramdef>uid_t <parameter>loginuid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>task</parameter></term>
   <listitem>
    <para>
     task whose audit context is being modified
    </para>
   </listitem>
  </varlistentry>
  <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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_mq_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <function>__audit_mq_open </function></funcdef>
   <paramdef>int <parameter>oflag</parameter></paramdef>
   <paramdef>mode_t <parameter>mode</parameter></paramdef>
   <paramdef>struct mq_attr __user * <parameter>u_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>u_attr</parameter></term>
   <listitem>
    <para>
     queue attributes
    </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-mq-timedsend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_mq_timedsend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_mq_timedsend</refname>
 <refpurpose>
     record audit data for a POSIX MQ timed send
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__audit_mq_timedsend </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 __user * <parameter>u_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>u_abs_timeout</parameter></term>
   <listitem>
    <para>
     Message timeout in absolute time
    </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-mq-timedreceive">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_mq_timedreceive</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_mq_timedreceive</refname>
 <refpurpose>
     record audit data for a POSIX MQ timed receive
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>__audit_mq_timedreceive </function></funcdef>
   <paramdef>mqd_t <parameter>mqdes</parameter></paramdef>
   <paramdef>size_t <parameter>msg_len</parameter></paramdef>
   <paramdef>unsigned int __user * <parameter>u_msg_prio</parameter></paramdef>
   <paramdef>const struct timespec __user * <parameter>u_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>u_msg_prio</parameter></term>
   <listitem>
    <para>
     Message priority
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>u_abs_timeout</parameter></term>
   <listitem>
    <para>
     Message timeout in absolute time
    </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-mq-notify">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_mq_notify</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <function>__audit_mq_notify </function></funcdef>
   <paramdef>mqd_t <parameter>mqdes</parameter></paramdef>
   <paramdef>const struct sigevent __user * <parameter>u_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>u_notification</parameter></term>
   <listitem>
    <para>
     Notification event
    </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-mq-getsetattr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_mq_getsetattr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success or NULL context or &lt; 0 on error.
</para>
</refsect1>
</refentry>

<refentry id="API---audit-ipc-obj">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_ipc_obj</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__audit_ipc_obj</refname>
 <refpurpose>
     record audit data for ipc object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <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>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success or NULL context or &lt; 0 on error.
</para>
</refsect1>
</refentry>

<refentry id="API---audit-ipc-set-perm">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_ipc_set_perm</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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>mode_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>
   Returns 0 for success or NULL context or &lt; 0 on error.
</para>
</refsect1>
</refentry>

<refentry id="API-audit-socketcall">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_socketcall</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args</parameter></term>
   <listitem>
    <para>
     args array
    </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-fd-pair">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_fd_pair</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>int <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>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success or NULL context or &lt; 0 on error.
</para>
</refsect1>
</refentry>

<refentry id="API-audit-sockaddr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_sockaddr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__audit_signal_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-core-dumps">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_core_dumps</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-receive-filter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>audit_receive_filter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>audit_receive_filter</refname>
 <refpurpose>
  apply all rules to the specified message type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>audit_receive_filter </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>int <parameter>pid</parameter></paramdef>
   <paramdef>int <parameter>uid</parameter></paramdef>
   <paramdef>int <parameter>seq</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>datasz</parameter></paramdef>
   <paramdef>uid_t <parameter>loginuid</parameter></paramdef>
   <paramdef>u32 <parameter>sid</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>pid</parameter></term>
   <listitem>
    <para>
     target pid for netlink audit messages
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uid</parameter></term>
   <listitem>
    <para>
     target uid 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>
  <varlistentry>
   <term><parameter>loginuid</parameter></term>
   <listitem>
    <para>
     loginuid of sender
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sid</parameter></term>
   <listitem>
    <para>
     SE Linux Security ID of sender
    </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sys_acct</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-auto-close-mnt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acct_auto_close_mnt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acct_auto_close_mnt</refname>
 <refpurpose>
     turn off a filesystem's accounting if it is on
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>acct_auto_close_mnt </function></funcdef>
   <paramdef>struct vfsmount * <parameter>m</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     vfsmount being shut down
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the accounting is turned on for a file in the subtree pointed to
   to by m, turn accounting off.  Done when m is about to die.
</para>
</refsect1>
</refentry>

<refentry id="API-acct-auto-close">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acct_auto_close</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acct_auto_close</refname>
 <refpurpose>
     turn off a filesystem's accounting if it is on
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>acct_auto_close </function></funcdef>
   <paramdef>struct super_block * <parameter>sb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sb</parameter></term>
   <listitem>
    <para>
     super block for the filesystem
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the accounting is turned on for a file in the filesystem pointed
   to by sb, turn accounting off.
</para>
</refsect1>
</refentry>

<refentry id="API-acct-init-pacct">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acct_init_pacct</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acct_init_pacct</refname>
 <refpurpose>
     initialize a new pacct_struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>acct_init_pacct </function></funcdef>
   <paramdef>struct pacct_struct * <parameter>pacct</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pacct</parameter></term>
   <listitem>
    <para>
     per-process accounting info struct to initialize
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-acct-collect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acct_collect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acct_process</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acct_process</refname>
 <refpurpose>
     now just a wrapper around do_acct_process
 </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>
   handles process accounting for an exiting task
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="pmfuncs">
     <title>Power Management</title>
<!-- kernel/power/pm.c -->
<refentry id="API-pm-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pm_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pm_register</refname>
 <refpurpose>
  register a device with power management
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pm_dev * <function>pm_register </function></funcdef>
   <paramdef>pm_dev_t <parameter>type</parameter></paramdef>
   <paramdef>unsigned long <parameter>id</parameter></paramdef>
   <paramdef>pm_callback <parameter>callback</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     device type 
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     device ID
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>callback</parameter></term>
   <listitem>
    <para>
     callback function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add a device to the list of devices that wish to be notified about
   power management events. A &amp;pm_dev structure is returned on success,
   on failure the return is <constant>NULL</constant>.
   </para><para>

   The callback function will be called in process context and
   it may sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-pm-send-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pm_send_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pm_send_all</refname>
 <refpurpose>
     send request to all managed devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pm_send_all </function></funcdef>
   <paramdef>pm_request_t <parameter>rqst</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rqst</parameter></term>
   <listitem>
    <para>
     power management request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data for the callback
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Issue a power management request to a all devices. The 
   <constant>PM_SUSPEND</constant> events are handled specially. Any device is 
   permitted to fail a suspend by returning a non zero (error)
   value from its callback function. If any device vetoes a 
   suspend request then all other devices that have suspended 
   during the processing of this request are restored to their
   previous state.
</para>
</refsect1>
<refsect1>
<title>WARNING</title>
<para>
   This function takes the pm_devs_lock. The lock is not dropped until
   the callbacks have completed. This prevents races against pm locking
   functions, races against module unload pm_unregister code. It does
   mean however that you must not issue pm_ functions within the callback
   or you will deadlock and users will hate you.
   </para><para>

   Zero is returned on success. If a suspend fails then the status
   from the device that vetoes the suspend is returned.
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
   what stops two power management requests occurring in parallel
   and conflicting.
</para>
</refsect1>
</refentry>

  </chapter>

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

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

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

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

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

<refentry id="API-get-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>get_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>get_driver</refname>
 <refpurpose>
     increment driver reference count.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct device_driver * <function>get_driver </function></funcdef>
   <paramdef>struct device_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     driver.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-put-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>put_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>put_driver</refname>
 <refpurpose>
     decrement driver's refcount.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>put_driver </function></funcdef>
   <paramdef>struct device_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     driver.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

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

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

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

   Note that kset_find_obj increments driver's reference count.
</para>
</refsect1>
</refentry>

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

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

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

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

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

<refentry id="API-device-schedule-callback-owner">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_schedule_callback_owner</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_schedule_callback_owner</refname>
 <refpurpose>
     helper to schedule a callback for a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_schedule_callback_owner </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>void (*<parameter>func</parameter>)
     <funcparams>struct device *</funcparams></paramdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>func</parameter></term>
   <listitem>
    <para>
     callback function to invoke later.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     module owning the callback routine
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Attribute methods must not unregister themselves or their parent device
   (which would amount to the same thing).  Attempts to do so will deadlock,
   since unregistration is mutually exclusive with driver callbacks.
   </para><para>

   Instead methods can call this routine, which will attempt to allocate
   and schedule a workqueue request to call back <parameter>func</parameter> with <parameter>dev</parameter> as its
   argument in the workqueue's process context.  <parameter>dev</parameter> will be pinned until
   <parameter>func</parameter> returns.
   </para><para>

   This routine is usually called via the inline <function>device_schedule_callback</function>,
   which automatically sets <parameter>owner</parameter> to THIS_MODULE.
   </para><para>

   Returns 0 if the request was submitted, -ENOMEM if storage could not
   be allocated, -ENODEV if a reference to <parameter>owner</parameter> isn't available.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   This routine won't work if CONFIG_SYSFS isn't set!  It uses an
   underlying sysfs routine (since it is intended for use by attribute
   methods), and if sysfs isn't available you'll get nothing but -ENOSYS.
</para>
</refsect1>
</refentry>

<refentry id="API-device-initialize">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_initialize</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_initialize</refname>
 <refpurpose>
     init device structure.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>device_initialize </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This prepares the device for use by other layers,
   including adding it to the device hierarchy.
   It is the first half of <function>device_register</function>, if called by
   that, though it can also be called separately, so one
   may use <parameter>dev</parameter>'s fields (e.g. the refcount).
</para>
</refsect1>
</refentry>

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

   This adds it to the kobject hierarchy via <function>kobject_add</function>, adds it
   to the global and sibling lists for the device, then
   adds it to the other relevant subsystems of the driver model.
</para>
</refsect1>
</refentry>

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

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

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

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

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

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

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

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

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

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

   A <quote>dev</quote> file will be created, showing the dev_t for the device, if
   the dev_t is not 0,0.
   If a pointer to a parent struct device is passed in, the newly created
   struct device will be a child of that device in sysfs.
   The pointer to the struct device will be returned from the call.
   Any further sysfs files that might be required can be created using this
   pointer.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the struct class passed to this function must have previously
   been created with a call to <function>class_create</function>.
</para>
</refsect1>
</refentry>

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

<refentry id="API-device-rename">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_rename</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_rename</refname>
 <refpurpose>
     renames a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_rename </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>char * <parameter>new_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the pointer to the struct device to be renamed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_name</parameter></term>
   <listitem>
    <para>
     the new name of the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

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

<!-- drivers/base/class.c -->
<refentry id="API-class-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_create</refname>
 <refpurpose>
  create a struct class structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct class * <function>class_create </function></funcdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     pointer to the module that is to <quote>own</quote> this struct class
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     pointer to a string for the name of this class.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is used to create a struct class pointer that can then be used
   in calls to <function>class_device_create</function>.
   </para><para>

   Note, the pointer created here is to be destroyed when finished by
   making a call to <function>class_destroy</function>.
</para>
</refsect1>
</refentry>

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

<refentry id="API-class-device-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>class_device_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>class_device_create</refname>
 <refpurpose>
     creates a class device and registers it with sysfs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct class_device * <function>class_device_create </function></funcdef>
   <paramdef>struct class * <parameter>cls</parameter></paramdef>
   <paramdef>struct class_device * <parameter>parent</parameter></paramdef>
   <paramdef>dev_t <parameter>devt</parameter></paramdef>
   <paramdef>struct device * <parameter>device</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cls</parameter></term>
   <listitem>
    <para>
     pointer to the struct class that this device should be registered to.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     pointer to the parent struct class_device of this new device, if any.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>devt</parameter></term>
   <listitem>
    <para>
     the dev_t for the char device to be added.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     a pointer to a struct device that is assiociated with this class device.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     string for the class device's name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can be used by char device classes.  A struct
   class_device will be created in sysfs, registered to the specified
   class.
   A <quote>dev</quote> file will be created, showing the dev_t for the device, if
   the dev_t is not 0,0.
   If a pointer to a parent struct class_device is passed in, the newly
   created struct class_device will be a child of that device in sysfs.
   The pointer to the struct class_device will be returned from the
   call.  Any further sysfs files that might be required can be created
   using this pointer.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the struct class passed to this function must have previously
   been created with a call to <function>class_create</function>.
</para>
</refsect1>
</refentry>

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

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

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

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

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

<refentry id="API-request-firmware-nowait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>request_firmware_nowait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>request_firmware_nowait</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>request_firmware_nowait </function></funcdef>
   <paramdef>struct module * <parameter>module</parameter></paramdef>
   <paramdef>int <parameter>uevent</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct device * <parameter>device</parameter></paramdef>
   <paramdef>void * <parameter>context</parameter></paramdef>
   <paramdef>void (*<parameter>cont</parameter>)
     <funcparams>const struct firmware *fw, void *context</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>module</parameter></term>
   <listitem>
    <para>
     module requesting the firmware
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uevent</parameter></term>
   <listitem>
    <para>
     sends uevent to copy the firmware image if this flag
     is non-zero else the firmware copy must be done manually.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of firmware file
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     device for which firmware is being loaded
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>context</parameter></term>
   <listitem>
    <para>
     will be passed over to <parameter>cont</parameter>, and
     <parameter>fw</parameter> may be <constant>NULL</constant> if firmware request fails.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cont</parameter></term>
   <listitem>
    <para>
     function will be called asynchronously when the firmware
     request is over.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Asynchronous variant of <function>request_firmware</function> for contexts where
   it is not possible to sleep.
</para>
</refsect1>
</refentry>

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

   Returns 0 on success or error on failure.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The transport class contains an embedded class which is used to
   identify it.  The caller should initialise this structure with
   zeros and then generic class must have been initialised with the
   actual transport class unique name.  There's a macro
   <function>DECLARE_TRANSPORT_CLASS</function> to do this (declared classes still must
   be registered).
   </para><para>

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

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

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

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

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

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

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

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

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

<!-- drivers/base/dmapool.c -->
<refentry id="API-dma-pool-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_pool_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>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>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 allocation 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_pool_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_pool_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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, null is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-dma-pool-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dma_pool_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmam_pool_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>dmam_pool_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

<!-- Cannot be included, because
     attribute_container_add_class_device_adapter
 and attribute_container_classdev_to_container
     exceed allowed 44 characters maximum
X!Edrivers/base/attribute_container.c
-->
<!-- drivers/base/sys.c -->
<refentry id="API-sysdev-driver-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sysdev_driver_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sysdev_driver_register</refname>
 <refpurpose>
  Register auxillary driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sysdev_driver_register </function></funcdef>
   <paramdef>struct sysdev_class * <parameter>cls</parameter></paramdef>
   <paramdef>struct sysdev_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cls</parameter></term>
   <listitem>
    <para>
     Device class driver belongs to.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     Driver.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If <parameter>cls</parameter> is valid, then <parameter>drv</parameter> is inserted into <parameter>cls</parameter>-&gt;drivers to be
   called on each operation on devices of that class. The refcount
   of <parameter>cls</parameter> is incremented.
   Otherwise, <parameter>drv</parameter> is inserted into sysdev_drivers, and called for
   each device.
</para>
</refsect1>
</refentry>

<refentry id="API-sysdev-driver-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sysdev_driver_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sysdev_driver_unregister</refname>
 <refpurpose>
     Remove an auxillary driver.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>sysdev_driver_unregister </function></funcdef>
   <paramdef>struct sysdev_class * <parameter>cls</parameter></paramdef>
   <paramdef>struct sysdev_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cls</parameter></term>
   <listitem>
    <para>
     Class driver belongs to.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     Driver.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-sysdev-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>sysdev_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>sysdev_register</refname>
 <refpurpose>
     add a system device to the tree
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>sysdev_register </function></funcdef>
   <paramdef>struct sys_device * <parameter>sysdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sysdev</parameter></term>
   <listitem>
    <para>
     device in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

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

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

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

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

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

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

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

   This device will be marked as not supporting hotpluggable drivers; no
   device add/remove uevents will be generated.  In the unusual case that
   the device isn't being dynamically allocated as a legacy <quote>probe the
   hardware</quote> driver, infrastructure code should reverse this marking.
</para>
</refsect1>
</refentry>

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

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

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

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

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

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

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

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

<refentry id="API-platform-driver-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>platform_driver_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>platform_driver_register</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>platform_driver_register </function></funcdef>
   <paramdef>struct platform_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     platform driver structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

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

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

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

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

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

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

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

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

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

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

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

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

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

     </sect1>
     <sect1><title>Device Drivers Power Management</title>
<!-- drivers/base/power/resume.c -->
<refentry id="API-device-resume">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_resume</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_resume</refname>
 <refpurpose>
  Restore state of each device in system.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>device_resume </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Walk the dpm_off list, remove each entry, resume the device,
   then add it to the dpm_active list.
</para>
</refsect1>
</refentry>

<refentry id="API-device-power-up">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_power_up</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_power_up</refname>
 <refpurpose>
     Turn on all devices that need special attention.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>device_power_up </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Power on system devices then devices that required we shut them down
   with interrupts disabled.
   Called with interrupts disabled.
</para>
</refsect1>
</refentry>

<!-- drivers/base/power/suspend.c -->
<refentry id="API-device-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_suspend</refname>
 <refpurpose>
  Save state and stop all devices in system.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_suspend </function></funcdef>
   <paramdef>pm_message_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     Power state to put each device in.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Walk the dpm_active list, call -&gt;<function>suspend</function> for each device, and move
   it to the dpm_off list.
   </para><para>

   (For historical reasons, if it returns -EAGAIN, that used to mean
   that the device would be called again with interrupts disabled.
   These days, we use the <quote><function>suspend_late</function></quote> callback for that, so we
   print a warning and consider it an error).
   </para><para>

   If we get a different error, try and back out.
   </para><para>

   If we hit a failure with any of the devices, call <function>device_resume</function>
   above to bring the suspended devices back to life.
</para>
</refsect1>
</refentry>

<refentry id="API-device-power-down">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>device_power_down</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>device_power_down</refname>
 <refpurpose>
     Shut down special devices.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>device_power_down </function></funcdef>
   <paramdef>pm_message_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     Power state to enter.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Walk the dpm_off_irq list, calling -&gt;<function>power_down</function> for each device that
   couldn't power down the device with interrupts enabled. When we're
   done, power down system devices.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Device Drivers ACPI Support</title>
<!-- Internal functions only
X!Edrivers/acpi/sleep/main.c
X!Edrivers/acpi/sleep/wakeup.c
X!Edrivers/acpi/motherboard.c
X!Edrivers/acpi/bus.c
-->
<!-- drivers/acpi/scan.c -->
<refentry id="API-acpi-bus-register-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acpi_bus_register_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acpi_bus_register_driver</refname>
 <refpurpose>
  register a driver with the ACPI bus
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>acpi_bus_register_driver </function></funcdef>
   <paramdef>struct acpi_driver * <parameter>driver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     driver being registered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers a driver with the ACPI bus.  Searches the namespace for all
   devices that match the driver's criteria and binds.  Returns zero for
   success or a negative error status for failure.
</para>
</refsect1>
</refentry>

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

<!-- drivers/acpi/scan.c -->
<refentry id="API-acpi-bus-driver-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>acpi_bus_driver_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>acpi_bus_driver_init</refname>
 <refpurpose>
  add a device to a driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>acpi_bus_driver_init </function></funcdef>
   <paramdef>struct acpi_device * <parameter>device</parameter></paramdef>
   <paramdef>struct acpi_driver * <parameter>driver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device to add and initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     driver for the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Used to initialize a device via its device driver.  Called whenever a 
   driver is bound to a device.  Invokes the driver's <function>add</function> ops.
</para>
</refsect1>
</refentry>

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

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

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

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

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

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

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

<!-- drivers/pnp/manager.c -->
<refentry id="API-pnp-init-resource-table">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_init_resource_table</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_init_resource_table</refname>
 <refpurpose>
  Resets a resource table to default values.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pnp_init_resource_table </function></funcdef>
   <paramdef>struct pnp_resource_table * <parameter>table</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>table</parameter></term>
   <listitem>
    <para>
     pointer to the desired resource table
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-pnp-manual-config-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_manual_config_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_manual_config_dev</refname>
 <refpurpose>
     Disables Auto Config and Manually sets the resource table
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>pnp_manual_config_dev </function></funcdef>
   <paramdef>struct pnp_dev * <parameter>dev</parameter></paramdef>
   <paramdef>struct pnp_resource_table * <parameter>res</parameter></paramdef>
   <paramdef>int <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to the desired device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>res</parameter></term>
   <listitem>
    <para>
     pointer to the new resource config
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     0 or PNP_CONFIG_FORCE
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can be used by drivers that want to manually set thier resources.
</para>
</refsect1>
</refentry>

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

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

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

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

<refentry id="API-pnp-resource-change">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>pnp_resource_change</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>pnp_resource_change</refname>
 <refpurpose>
     change one resource
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>pnp_resource_change </function></funcdef>
   <paramdef>struct resource * <parameter>resource</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>resource</parameter></term>
   <listitem>
    <para>
     pointer to resource to be changed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     start of region
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of region
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

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

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

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

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

<!-- include/linux/uio_driver.h -->
<refentry id="API-struct-uio-mem">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct uio_mem</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct uio_mem</refname>
 <refpurpose>
  description of a UIO memory region
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct uio_mem {
  struct kobject kobj;
  unsigned long addr;
  unsigned long size;
  int memtype;
  void __iomem * internal_addr;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>kobj</term>
      <listitem><para>
kobject for this mapping
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>addr</term>
      <listitem><para>
address of the device's memory
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>size</term>
      <listitem><para>
size of IO
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>memtype</term>
      <listitem><para>
type of memory addr points to
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>internal_addr</term>
      <listitem><para>
ioremap-ped version of addr, for driver internal use
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

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

     </sect1>
  </chapter>

  <chapter id="blkdev">
     <title>Block Devices</title>
<!-- block/ll_rw_blk.c -->
<refentry id="API-blk-get-backing-dev-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_get_backing_dev_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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
   </para><para>

   Will return NULL if the request queue cannot be located.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-prep-rq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_prep_rq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-merge-bvec">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_merge_bvec</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-queue-make-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_make_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 &amp;struct bios 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-ordered">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_ordered</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_ordered</refname>
 <refpurpose>
     does this queue support ordered writes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_queue_ordered </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned <parameter>ordered</parameter></paramdef>
   <paramdef>prepare_flush_fn * <parameter>prepare_flush_fn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ordered</parameter></term>
   <listitem>
    <para>
     one of QUEUE_ORDERED_*
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prepare_flush_fn</parameter></term>
   <listitem>
    <para>
     rq setup helper for cache flush ordered writes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   For journalled file systems, doing ordered writes on a commit
   block instead of explicitly doing wait_on_buffer (which is bad
   for performance) can be a big win. Block drivers supporting this
   feature should call this function and indicate so.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-issue-flush-fn">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_issue_flush_fn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_issue_flush_fn</refname>
 <refpurpose>
     set function for issuing a flush
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_issue_flush_fn </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>issue_flush_fn * <parameter>iff</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     the request queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>iff</parameter></term>
   <listitem>
    <para>
     the function to be called issuing the flush
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a driver supports issuing a flush command, the support is notified
   to the block layer by defining it through this call.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-bounce-limit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_bounce_limit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>dma_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>dma_addr</parameter></term>
   <listitem>
    <para>
     bus address limit
    </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>page</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-max-sectors">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_max_sectors</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_max_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_sectors </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>unsigned int <parameter>max_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_sectors</parameter></term>
   <listitem>
    <para>
     max sectors in the usual 512b unit
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enables a low level driver to set an upper limit on the size of
   received requests.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-max-phys-segments">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_max_phys_segments</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_max_phys_segments</refname>
 <refpurpose>
     set max phys segments for a request for this queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_max_phys_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
   physical data segments in a request.  This would be the largest sized
   scatter list the driver could handle.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-max-hw-segments">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_max_hw_segments</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_max_hw_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_hw_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.  This would be the largest number of
   address/length pairs the host adapter can actually give as once
   to the device.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-max-segment-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_max_segment_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-hardsect-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_hardsect_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_queue_hardsect_size</refname>
 <refpurpose>
     set hardware sector size for the queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_queue_hardsect_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 hardware sector size, in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This should typically be set to the lowest possible sector size
   that the hardware can operate on (possible without reverting to
   even internal read-modify-write operations). Usually the default
   of 512 covers most hardware.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-stack-limits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_stack_limits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-queue-segment-boundary">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_segment_boundary</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_dma_alignment</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 aligment for direct dma transactions.
   this is used when buiding direct io requests for the queue.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-find-tag">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_find_tag</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_free_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
   For externally managed <parameter>bqt</parameter>@ frees the map.  Callers of this
   function must guarantee to have released all the queues that
   might have been using this tag map.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-queue-free-tags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_free_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 disabled 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_init_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>depth</parameter></term>
   <listitem>
    <para>
     the maximum queue depth supported
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-blk-queue-init-tags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_init_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
  </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>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-blk-queue-resize-tags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_resize_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_end_tag</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 0, 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_start_tag</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 &amp;prep_rq_fn (in which case &amp;struct request
   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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_queue_invalidate_tags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>

<refentry id="API-generic-unplug-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_unplug_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_unplug_device</refname>
 <refpurpose>
     fire a request queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>generic_unplug_device </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 &amp;struct request_queue in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Linux uses plugging to build bigger requests queues before letting
   the device have at them. If a queue is plugged, the I/O scheduler
   is still adding and merging requests on the queue. Once the queue
   gets unplugged, the request_fn defined for the queue is invoked and
   transfers started.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-start-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_start_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 &amp;struct request_queue 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_stop_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 &amp;struct request_queue 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_sync_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refsect1>
</refentry>

<refentry id="API-blk-run-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_run_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
</refentry>

<refentry id="API-blk-init-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_init_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 NULL 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-start-queueing">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_start_queueing</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_start_queueing</refname>
 <refpurpose>
     initiate dispatch of requests to device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_start_queueing </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 kick into gear
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is basically a helper to remove the need to know whether a queue
   is plugged or not if someone just wants to initiate dispatch of requests
   for this queue.
   </para><para>

   The queue lock must be held with interrupts disabled.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-requeue-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_requeue_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-blk-insert-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_insert_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_insert_request</refname>
 <refpurpose>
     insert a special request in to a request queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_insert_request </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>int <parameter>at_head</parameter></paramdef>
   <paramdef>void * <parameter>data</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>
  <varlistentry>
   <term><parameter>at_head</parameter></term>
   <listitem>
    <para>
     insert request at head or tail of queue
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     private data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Many block devices need to execute commands asynchronously, so they don't
   block the whole kernel from preemption during request execution.  This is
   accomplished normally by inserting aritficial requests tagged as
   REQ_SPECIAL in to the corresponding request queue, and letting them be
   scheduled for actual execution by the request queue.
   </para><para>

   We have the option of inserting the head or the tail of the queue.
   Typically we use the tail for new ioctls and so forth.  We use the head
   of the queue for things like a QUEUE_FULL message from a device, or a
   host that is unable to accept a particular command.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-rq-map-user">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_map_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_map_user</refname>
 <refpurpose>
     map user data to a request, for REQ_BLOCK_PC usage
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>blk_rq_map_user </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>rq</parameter></paramdef>
   <paramdef>void __user * <parameter>ubuf</parameter></paramdef>
   <paramdef>unsigned long <parameter>len</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 structure to fill
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ubuf</parameter></term>
   <listitem>
    <para>
     the user buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of user data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Data will be mapped directly for zero copy io, 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 io, 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-map-user-iov">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_map_user_iov</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_map_user_iov</refname>
 <refpurpose>
     map user data to a request, for REQ_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 sg_iovec * <parameter>iov</parameter></paramdef>
   <paramdef>int <parameter>iov_count</parameter></paramdef>
   <paramdef>unsigned int <parameter>len</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>iov</parameter></term>
   <listitem>
    <para>
     pointer to the iovec
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>iov_count</parameter></term>
   <listitem>
    <para>
     number of elements in the iovec
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     I/O byte count
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Data will be mapped directly for zero copy io, 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 io, 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_unmap_user</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 io 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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_rq_map_kern</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_rq_map_kern</refname>
 <refpurpose>
     map kernel data to a request, for REQ_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>
</refentry>

<refentry id="API-blk-execute-rq-nowait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_execute_rq_nowait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 io scheduler queue
   for execution.  Don't wait for completion.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-execute-rq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_execute_rq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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 io scheduler queue
   for execution and wait for completion.
</para>
</refsect1>
</refentry>

<refentry id="API-blkdev-issue-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blkdev_issue_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>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>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.  Caller must run <function>wait_for_completion</function> on its own.
</para>
</refsect1>
</refentry>

<refentry id="API-blk-end-sync-rq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_end_sync_rq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_end_sync_rq</refname>
 <refpurpose>
     executes a completion event on a request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_end_sync_rq </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>
     request to complete
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error</parameter></term>
   <listitem>
    <para>
     end io status of the request
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-submit-bio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>submit_bio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>submit_bio</refname>
 <refpurpose>
   </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 &amp;struct bio 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-end-that-request-first">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>end_that_request_first</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>end_that_request_first</refname>
 <refpurpose>
     end I/O on a request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>end_that_request_first </function></funcdef>
   <paramdef>struct request * <parameter>req</parameter></paramdef>
   <paramdef>int <parameter>uptodate</parameter></paramdef>
   <paramdef>int <parameter>nr_sectors</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>uptodate</parameter></term>
   <listitem>
    <para>
     1 for success, 0 for I/O error, &lt; 0 for specific error
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_sectors</parameter></term>
   <listitem>
    <para>
     number of sectors to end I/O on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Ends I/O on a number of sectors attached to <parameter>req</parameter>, and sets it up
   for the next range of segments (if any) in the cluster.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 - we are done with this request, call <function>end_that_request_last</function>
   1 - still buffers pending for this request
</para>
</refsect1>
</refentry>

<refentry id="API-end-that-request-chunk">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>end_that_request_chunk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>end_that_request_chunk</refname>
 <refpurpose>
     end I/O on a request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>end_that_request_chunk </function></funcdef>
   <paramdef>struct request * <parameter>req</parameter></paramdef>
   <paramdef>int <parameter>uptodate</parameter></paramdef>
   <paramdef>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>uptodate</parameter></term>
   <listitem>
    <para>
     1 for success, 0 for I/O error, &lt; 0 for specific 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>req</parameter>, and sets it up
   for the next range of segments (if any). Like <function>end_that_request_first</function>,
   but deals with bytes instead of sectors.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 - we are done with this request, call <function>end_that_request_last</function>
   1 - still buffers pending for this request
</para>
</refsect1>
</refentry>

<refentry id="API-blk-complete-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>blk_complete_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>blk_complete_request</refname>
 <refpurpose>
     end I/O on a request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>blk_complete_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 being processed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Ends all I/O on a request. It does not handle partial completions,
   unless the driver actually implements this in its completion callback
   through requeueing. Theh actual completion happens out-of-order,
   through a softirq handler. The user must have registered a completion
   callback through <function>blk_queue_softirq_done</function>.
</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_chrdev_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>alloc_chrdev_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_chrdev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_chrdev</refname>
 <refpurpose>
     Register a major number for character devices.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_chrdev </function></funcdef>
   <paramdef>unsigned int <parameter>major</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>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><para>

   This function registers a range of 256 minor numbers. The first minor number
   is 0.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-chrdev-region">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_chrdev_region</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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-cdev-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cdev_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cdev_del</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cdev_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>cdev_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>misc_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<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><para>

   The structure passed is linked into the kernel and may not be
   destroyed until it has been unregistered.
   </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>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>misc_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</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="parportdev">
     <title>Parallel Port Devices</title>
<!-- include/linux/parport.h -->
<refentry id="API-parport-yield">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_yield</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_yield</refname>
 <refpurpose>
  relinquish a parallel port temporarily
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_yield </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     a device on the parallel port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function relinquishes the port if it would be helpful to other
   drivers to do so.  Afterwards it tries to reclaim the port using
   <function>parport_claim</function>, and the return value is the same as for
   <function>parport_claim</function>.  If it fails, the port is left unclaimed and it is
   the driver's responsibility to reclaim the port.
   </para><para>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<refentry id="API-parport-set-timeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_set_timeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_set_timeout</refname>
 <refpurpose>
     set the inactivity timeout for a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>parport_set_timeout </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
   <paramdef>long <parameter>inactivity</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device on a port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>inactivity</parameter></term>
   <listitem>
    <para>
     inactivity timeout (in jiffies)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This sets the inactivity timeout for a particular device on a
   port.  This affects functions like <function>parport_wait_peripheral</function>.
   The special value 0 means not to call <function>schedule</function> while dealing
   with this device.
   </para><para>

   The return value is the previous inactivity timeout.
   </para><para>

   Any callers of <function>parport_wait_event</function> for this device are woken
   up.
</para>
</refsect1>
</refentry>

<!-- drivers/parport/share.c -->
<refentry id="API-parport-register-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_register_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_register_driver</refname>
 <refpurpose>
  register a parallel port device driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_register_driver </function></funcdef>
   <paramdef>struct parport_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     structure describing the driver
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This can be called by a parallel port device driver in order
   to receive notifications about ports being found in the
   system, as well as ports no longer available.
   </para><para>

   The <parameter>drv</parameter> structure is allocated by the caller and must not be
   deallocated until after calling <function>parport_unregister_driver</function>.
   </para><para>

   The driver's <function>attach</function> function may block.  The port that
   <function>attach</function> is given will be valid for the duration of the
   callback, but if the driver wants to take a copy of the
   pointer it must call <function>parport_get_port</function> to do so.  Calling
   <function>parport_register_device</function> on that port will do this for you.
   </para><para>

   The driver's <function>detach</function> function may block.  The port that
   <function>detach</function> is given will be valid for the duration of the
   callback, but if the driver wants to take a copy of the
   pointer it must call <function>parport_get_port</function> to do so.
   </para><para>

   Returns 0 on success.  Currently it always succeeds.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-unregister-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_unregister_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_unregister_driver</refname>
 <refpurpose>
     deregister a parallel port device driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_unregister_driver </function></funcdef>
   <paramdef>struct parport_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     structure describing the driver that was given to
     <function>parport_register_driver</function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This should be called by a parallel port device driver that
   has registered itself using <function>parport_register_driver</function> when it
   is about to be unloaded.
   </para><para>

   When it returns, the driver's <function>attach</function> routine will no longer
   be called, and for each port that <function>attach</function> was called for, the
   <function>detach</function> routine will have been called.
   </para><para>

   All the driver's <function>attach</function> and <function>detach</function> calls are guaranteed to have
   finished by the time this function returns.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-get-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_get_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_get_port</refname>
 <refpurpose>
     increment a port's reference count
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct parport * <function>parport_get_port </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     the port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This ensures that a struct parport pointer remains valid
   until the matching <function>parport_put_port</function> call.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-put-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_put_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_put_port</refname>
 <refpurpose>
     decrement a port's reference count
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_put_port </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     the port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This should be called once for each call to <function>parport_get_port</function>,
   once the port is no longer needed.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-register-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_register_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_register_port</refname>
 <refpurpose>
     register a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct parport * <function>parport_register_port </function></funcdef>
   <paramdef>unsigned long <parameter>base</parameter></paramdef>
   <paramdef>int <parameter>irq</parameter></paramdef>
   <paramdef>int <parameter>dma</parameter></paramdef>
   <paramdef>struct parport_operations * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     base I/O address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     IRQ line
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma</parameter></term>
   <listitem>
    <para>
     DMA channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     pointer to the port driver's port operations structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When a parallel port (lowlevel) driver finds a port that
   should be made available to parallel port device drivers, it
   should call <function>parport_register_port</function>.  The <parameter>base</parameter>, <parameter>irq</parameter>, and
   <parameter>dma</parameter> parameters are for the convenience of port drivers, and
   for ports where they aren't meaningful needn't be set to
   anything special.  They can be altered afterwards by adjusting
   the relevant members of the parport structure that is returned
   and represents the port.  They should not be tampered with
   after calling parport_announce_port, however.
   </para><para>

   If there are parallel port device drivers in the system that
   have registered themselves using <function>parport_register_driver</function>,
   they are not told about the port at this time; that is done by
   <function>parport_announce_port</function>.
   </para><para>

   The <parameter>ops</parameter> structure is allocated by the caller, and must not be
   deallocated before calling <function>parport_remove_port</function>.
   </para><para>

   If there is no memory to allocate a new parport structure,
   this function will return <constant>NULL</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-announce-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_announce_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_announce_port</refname>
 <refpurpose>
     tell device drivers about a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_announce_port </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     parallel port to announce
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   After a port driver has registered a parallel port with
   parport_register_port, and performed any necessary
   initialisation or adjustments, it should call
   <function>parport_announce_port</function> in order to notify all device drivers
   that have called <function>parport_register_driver</function>.  Their <function>attach</function>
   functions will be called, with <parameter>port</parameter> as the parameter.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-remove-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_remove_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_remove_port</refname>
 <refpurpose>
     deregister a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_remove_port </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     parallel port to deregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When a parallel port driver is forcibly unloaded, or a
   parallel port becomes inaccessible, the port driver must call
   this function in order to deal with device drivers that still
   want to use it.
   </para><para>

   The parport structure associated with the port has its
   operations structure replaced with one containing 'null'
   operations that return errors or just don't do anything.
   </para><para>

   Any drivers that have registered themselves using
   <function>parport_register_driver</function> are notified that the port is no
   longer accessible by having their <function>detach</function> routines called
   with <parameter>port</parameter> as the parameter.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-register-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_register_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_register_device</refname>
 <refpurpose>
     register a device on a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pardevice * <function>parport_register_device </function></funcdef>
   <paramdef>struct parport * <parameter>port</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>int (*<parameter>pf</parameter>)
     <funcparams>void *</funcparams></paramdef>
   <paramdef>void (*<parameter>kf</parameter>)
     <funcparams>void *</funcparams></paramdef>
   <paramdef>void (*<parameter>irq_func</parameter>)
     <funcparams>int, void *</funcparams></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
   <paramdef>void * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     port to which the device is attached
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     a name to refer to the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pf</parameter></term>
   <listitem>
    <para>
     preemption callback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kf</parameter></term>
   <listitem>
    <para>
     kick callback (wake-up)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>irq_func</parameter></term>
   <listitem>
    <para>
     interrupt handler
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     registration flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     data for callback functions
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function, called by parallel port device drivers,
   declares that a device is connected to a port, and tells the
   system all it needs to know.
   </para><para>

   The <parameter>name</parameter> is allocated by the caller and must not be
   deallocated until the caller calls <parameter>parport_unregister_device</parameter>
   for that device.
   </para><para>

   The preemption callback function, <parameter>pf</parameter>, is called when this
   device driver has claimed access to the port but another
   device driver wants to use it.  It is given <parameter>handle</parameter> as its
   parameter, and should return zero if it is willing for the
   system to release the port to another driver on its behalf.
   If it wants to keep control of the port it should return
   non-zero, and no action will be taken.  It is good manners for
   the driver to try to release the port at the earliest
   opportunity after its preemption callback rejects a preemption
   attempt.  Note that if a preemption callback is happy for
   preemption to go ahead, there is no need to release the port;
   it is done automatically.  This function may not block, as it
   may be called from interrupt context.  If the device driver
   does not support preemption, <parameter>pf</parameter> can be <constant>NULL</constant>.
   </para><para>

   The wake-up (<quote>kick</quote>) callback function, <parameter>kf</parameter>, is called when
   the port is available to be claimed for exclusive access; that
   is, <function>parport_claim</function> is guaranteed to succeed when called from
   inside the wake-up callback function.  If the driver wants to
   claim the port it should do so; otherwise, it need not take
   any action.  This function may not block, as it may be called
   from interrupt context.  If the device driver does not want to
   be explicitly invited to claim the port in this way, <parameter>kf</parameter> can
   be <constant>NULL</constant>.
   </para><para>

   The interrupt handler, <parameter>irq_func</parameter>, is called when an interrupt
   arrives from the parallel port.  Note that if a device driver
   wants to use interrupts it should use <function>parport_enable_irq</function>,
   and can also check the irq member of the parport structure
   representing the port.
   </para><para>

   The parallel port (lowlevel) driver is the one that has called
   <function>request_irq</function> and whose interrupt handler is called first.
   This handler does whatever needs to be done to the hardware to
   acknowledge the interrupt (for PC-style ports there is nothing
   special to be done).  It then tells the IEEE 1284 code about
   the interrupt, which may involve reacting to an IEEE 1284
   event depending on the current IEEE 1284 phase.  After this,
   it calls <parameter>irq_func</parameter>.  Needless to say, <parameter>irq_func</parameter> will be called
   from interrupt context, and may not block.
   </para><para>

   The <constant>PARPORT_DEV_EXCL</constant> flag is for preventing port sharing, and
   so should only be used when sharing the port with other device
   drivers is impossible and would lead to incorrect behaviour.
   Use it sparingly!  Normally, <parameter>flags</parameter> will be zero.
   </para><para>

   This function returns a pointer to a structure that represents
   the device on the port, or <constant>NULL</constant> if there is not enough memory
   to allocate space for that structure.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-unregister-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_unregister_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_unregister_device</refname>
 <refpurpose>
     deregister a device on a parallel port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_unregister_device </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to structure representing device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This undoes the effect of <function>parport_register_device</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-find-number">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_find_number</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_find_number</refname>
 <refpurpose>
     find a parallel port by number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct parport * <function>parport_find_number </function></funcdef>
   <paramdef>int <parameter>number</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>number</parameter></term>
   <listitem>
    <para>
     parallel port number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns the parallel port with the specified number, or
   <constant>NULL</constant> if there is none.
   </para><para>

   There is an implicit <function>parport_get_port</function> done already; to throw
   away the reference to the port that <function>parport_find_number</function>
   gives you, use <function>parport_put_port</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-find-base">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_find_base</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_find_base</refname>
 <refpurpose>
     find a parallel port by base address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct parport * <function>parport_find_base </function></funcdef>
   <paramdef>unsigned long <parameter>base</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>base</parameter></term>
   <listitem>
    <para>
     base I/O address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns the parallel port with the specified base
   address, or <constant>NULL</constant> if there is none.
   </para><para>

   There is an implicit <function>parport_get_port</function> done already; to throw
   away the reference to the port that <function>parport_find_base</function>
   gives you, use <function>parport_put_port</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-claim">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_claim</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_claim</refname>
 <refpurpose>
     claim access to a parallel port device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_claim </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to structure representing a device on the port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will not block and so can be used from interrupt
   context.  If <function>parport_claim</function> succeeds in claiming access to
   the port it returns zero and the port is available to use.  It
   may fail (returning non-zero) if the port is in use by another
   driver and that driver is not willing to relinquish control of
   the port.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-claim-or-block">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_claim_or_block</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_claim_or_block</refname>
 <refpurpose>
     claim access to a parallel port device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_claim_or_block </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to structure representing a device on the port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This behaves like <function>parport_claim</function>, but will block if necessary
   to wait for the port to be free.  A return value of 1
   indicates that it slept; 0 means that it succeeded without
   needing to sleep.  A negative error code indicates failure.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_release</refname>
 <refpurpose>
     give up access to a parallel port device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_release </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     pointer to structure representing parallel port device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function cannot fail, but it should not be called without
   the port claimed.  Similarly, if the port is already claimed
   you should not try claiming it again.
</para>
</refsect1>
</refentry>

<!-- drivers/parport/daisy.c -->
<refentry id="API-parport-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_open</refname>
 <refpurpose>
  find a device by canonical device number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct pardevice * <function>parport_open </function></funcdef>
   <paramdef>int <parameter>devnum</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>int (*<parameter>pf</parameter>)
     <funcparams>void *</funcparams></paramdef>
   <paramdef>void (*<parameter>kf</parameter>)
     <funcparams>void *</funcparams></paramdef>
   <paramdef>void (*<parameter>irqf</parameter>)
     <funcparams>int, void *</funcparams></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
   <paramdef>void * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>devnum</parameter></term>
   <listitem>
    <para>
     canonical device number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name to associate with the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pf</parameter></term>
   <listitem>
    <para>
     preemption callback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kf</parameter></term>
   <listitem>
    <para>
     kick callback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>irqf</parameter></term>
   <listitem>
    <para>
     interrupt handler
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     registration flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     driver data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is similar to <function>parport_register_device</function>, except
   that it locates a device by its number rather than by the port
   it is attached to.
   </para><para>

   All parameters except for <parameter>devnum</parameter> are the same as for
   <function>parport_register_device</function>.  The return value is the same as
   for <function>parport_register_device</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-close">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_close</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_close</refname>
 <refpurpose>
     close a device opened with <function>parport_open</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>parport_close </function></funcdef>
   <paramdef>struct pardevice * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to close
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is to <function>parport_open</function> as <function>parport_unregister_device</function> is to
   <function>parport_register_device</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-parport-device-num">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>parport_device_num</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>parport_device_num</refname>
 <refpurpose>
     convert device coordinates
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>parport_device_num </function></funcdef>
   <paramdef>int <parameter>parport</parameter></paramdef>
   <paramdef>int <parameter>mux</parameter></paramdef>
   <paramdef>int <parameter>daisy</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>parport</parameter></term>
   <listitem>
    <para>
     parallel port number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mux</parameter></term>
   <listitem>
    <para>
     multiplexor port number (-1 for no multiplexor)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>daisy</parameter></term>
   <listitem>
    <para>
     daisy chain address (-1 for no daisy chain address)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This tries to locate a device on the given parallel port,
   multiplexor port and daisy chain address, and returns its
   device number or <constant>-ENXIO</constant> if no device with those coordinates
   exists.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="message_devices">
	<title>Message-based devices</title>
     <sect1><title>Fusion message devices</title>
<!-- drivers/message/fusion/mptbase.c -->
<refentry id="API-mpt-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_register</refname>
 <refpurpose>
  Register protocol-specific main callback handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_register </function></funcdef>
   <paramdef>MPT_CALLBACK <parameter>cbfunc</parameter></paramdef>
   <paramdef>MPT_DRIVER_CLASS <parameter>dclass</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cbfunc</parameter></term>
   <listitem>
    <para>
     callback function pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dclass</parameter></term>
   <listitem>
    <para>
     Protocol driver's class (<constant>MPT_DRIVER_CLASS</constant> enum value)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is called by a protocol-specific driver (SCSI host,
   LAN, SCSI target) to register its reply callback routine.  Each
   protocol-specific driver must do this before it will be able to
   use any IOC resources, such as obtaining request frames.
</para>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   The SCSI protocol driver currently calls this routine thrice
   in order to register separate callbacks; one for <quote>normal</quote> SCSI IO;
   one for MptScsiTaskMgmt requests; one for Scan/DV requests.
   </para><para>

   Returns a positive integer valued <quote>handle</quote> in the
   range (and S.O.D. order) {N,...,7,6,5,...,1} if successful.
   Any non-positive return value (including zero!) should be considered
   an error by the caller.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-deregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_deregister</refname>
 <refpurpose>
     Deregister a protocol drivers resources.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_deregister </function></funcdef>
   <paramdef>int <parameter>cb_idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     previously registered callback handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each protocol-specific driver should call this routine when its
   module is unloaded.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-event-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_event_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_event_register</refname>
 <refpurpose>
     Register protocol-specific event callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_event_register </function></funcdef>
   <paramdef>int <parameter>cb_idx</parameter></paramdef>
   <paramdef>MPT_EVHANDLER <parameter>ev_cbfunc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     previously registered (via mpt_register) callback handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ev_cbfunc</parameter></term>
   <listitem>
    <para>
     callback function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine can be called by one or more protocol-specific drivers
   if/when they choose to be notified of MPT events.
   </para><para>

   Returns 0 for success.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine can be called by one or more protocol-specific drivers
   if/when they choose to be notified of MPT events.
   </para><para>

   Returns 0 for success.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-event-deregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_event_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_event_deregister</refname>
 <refpurpose>
     Deregister protocol-specific event callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_event_deregister </function></funcdef>
   <paramdef>int <parameter>cb_idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     previously registered callback handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each protocol-specific driver should call this routine
   when it does not (or can no longer) handle events,
   or when its module is unloaded.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each protocol-specific driver should call this routine
   when it does not (or can no longer) handle events,
   or when its module is unloaded.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-reset-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_reset_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_reset_register</refname>
 <refpurpose>
     Register protocol-specific IOC reset handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_reset_register </function></funcdef>
   <paramdef>int <parameter>cb_idx</parameter></paramdef>
   <paramdef>MPT_RESETHANDLER <parameter>reset_func</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     previously registered (via mpt_register) callback handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reset_func</parameter></term>
   <listitem>
    <para>
     reset function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine can be called by one or more protocol-specific drivers
   if/when they choose to be notified of IOC resets.
   </para><para>

   Returns 0 for success.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-reset-deregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_reset_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_reset_deregister</refname>
 <refpurpose>
     Deregister protocol-specific IOC reset handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_reset_deregister </function></funcdef>
   <paramdef>int <parameter>cb_idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     previously registered callback handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Each protocol-specific driver should call this routine
   when it does not (or can no longer) handle IOC reset handling,
   or when its module is unloaded.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-device-driver-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_device_driver_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_device_driver_register</refname>
 <refpurpose>
     Register device driver hooks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_device_driver_register </function></funcdef>
   <paramdef>struct mpt_pci_driver * <parameter>dd_cbfunc</parameter></paramdef>
   <paramdef>int <parameter>cb_idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dd_cbfunc</parameter></term>
   <listitem>
    <para>
     driver callbacks struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     MPT protocol driver index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-device-driver-deregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_device_driver_deregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_device_driver_deregister</refname>
 <refpurpose>
     DeRegister device driver hooks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_device_driver_deregister </function></funcdef>
   <paramdef>int <parameter>cb_idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cb_idx</parameter></term>
   <listitem>
    <para>
     MPT protocol driver index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-get-msg-frame">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_get_msg_frame</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_get_msg_frame</refname>
 <refpurpose>
     Obtain a MPT request frame from the pool (of 1024)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>MPT_FRAME_HDR* <function>mpt_get_msg_frame </function></funcdef>
   <paramdef>int <parameter>handle</parameter></paramdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     Handle of registered MPT protocol driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns pointer to a MPT request frame or <constant>NULL</constant> if none are available
   or IOC is not active.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns pointer to a MPT request frame or <constant>NULL</constant> if none are available
   or IOC is not active.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-put-msg-frame">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_put_msg_frame</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_put_msg_frame</refname>
 <refpurpose>
     Send a protocol specific MPT request frame
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_put_msg_frame </function></funcdef>
   <paramdef>int <parameter>handle</parameter></paramdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     Handle of registered MPT protocol driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine posts a MPT request frame to the request post FIFO of a
   specific MPT adapter.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine posts a MPT request frame to the request post FIFO of a
   specific MPT adapter.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-free-msg-frame">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_free_msg_frame</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_free_msg_frame</refname>
 <refpurpose>
     Place MPT request frame back on FreeQ.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_free_msg_frame </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places a MPT request frame back on the MPT adapter's
   FreeQ.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-add-sge">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_add_sge</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_add_sge</refname>
 <refpurpose>
     Place a simple SGE at address pAddr.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_add_sge </function></funcdef>
   <paramdef>char * <parameter>pAddr</parameter></paramdef>
   <paramdef>u32 <parameter>flagslength</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>dma_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pAddr</parameter></term>
   <listitem>
    <para>
     virtual address for SGE
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flagslength</parameter></term>
   <listitem>
    <para>
     SGE flags and data transfer length
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_addr</parameter></term>
   <listitem>
    <para>
     Physical address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places a MPT request frame back on the MPT adapter's
   FreeQ.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-send-handshake-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_send_handshake_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_send_handshake_request</refname>
 <refpurpose>
     Send MPT request via doorbell handshake method.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_send_handshake_request </function></funcdef>
   <paramdef>int <parameter>handle</parameter></paramdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>reqBytes</parameter></paramdef>
   <paramdef>u32 * <parameter>req</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     Handle of registered MPT protocol driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reqBytes</parameter></term>
   <listitem>
    <para>
     Size of the request in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Use schedule if CAN_SLEEP else use udelay.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is used exclusively to send MptScsiTaskMgmt
   requests since they are required to be sent via doorbell handshake.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   It is the callers responsibility to byte-swap fields in the
   request which are greater than 1 byte in size.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-verify-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_verify_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_verify_adapter</refname>
 <refpurpose>
     Given IOC identifier, set pointer to its adapter structure.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_verify_adapter </function></funcdef>
   <paramdef>int <parameter>iocid</parameter></paramdef>
   <paramdef>MPT_ADAPTER ** <parameter>iocpp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>iocid</parameter></term>
   <listitem>
    <para>
     IOC unique identifier (integer)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>iocpp</parameter></term>
   <listitem>
    <para>
     Pointer to pointer to IOC adapter
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a unique IOC identifier, set pointer to the associated MPT
   adapter structure.
   </para><para>

   Returns iocid and sets iocpp if iocid is found.
   Returns -1 if iocid is not found.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-attach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_attach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_attach</refname>
 <refpurpose>
     Install a PCI intelligent MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_attach </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>const struct pci_device_id * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to pci_dev structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     PCI device ID information
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine performs all the steps necessary to bring the IOC of
   a MPT adapter to a OPERATIONAL state.  This includes registering
   memory regions, registering the interrupt, and allocating request
   and reply memory pools.
   </para><para>

   This routine also pre-fetches the LAN MAC address of a Fibre Channel
   MPT adapter.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
<refsect1>
<title>TODO</title>
<para>
   Add support for polled controllers
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-detach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_detach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_detach</refname>
 <refpurpose>
     Remove a PCI intelligent MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_detach </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to pci_dev structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_suspend</refname>
 <refpurpose>
     Fusion MPT base driver suspend routine.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_suspend </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>pm_message_t <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to pci_dev structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     new state to enter
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-resume">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_resume</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_resume</refname>
 <refpurpose>
     Fusion MPT base driver resume routine.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_resume </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to pci_dev structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-GetIocState">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_GetIocState</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_GetIocState</refname>
 <refpurpose>
     Get the current state of a MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>mpt_GetIocState </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>cooked</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cooked</parameter></term>
   <listitem>
    <para>
     Request raw or cooked IOC state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns all IOC Doorbell register bits if cooked==0, else just the
   Doorbell bits in MPI_IOC_STATE_MASK.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-alloc-fw-memory">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_alloc_fw_memory</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_alloc_fw_memory</refname>
 <refpurpose>
     allocate firmware memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_alloc_fw_memory </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     total FW bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If memory has already been allocated, the same (cached) value
   is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-free-fw-memory">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_free_fw_memory</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_free_fw_memory</refname>
 <refpurpose>
     free firmware memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_free_fw_memory </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If alt_img is NULL, delete from ioc structure.
   Else, delete a secondary image in same format.
</para>
</refsect1>
</refentry>

<refentry id="API-mptbase-sas-persist-operation">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptbase_sas_persist_operation</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptbase_sas_persist_operation</refname>
 <refpurpose>
     Perform operation on SAS Persistent Table
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptbase_sas_persist_operation </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>persist_opcode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>persist_opcode</parameter></term>
   <listitem>
    <para>
     see below
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   MPI_SAS_OP_CLEAR_NOT_PRESENT - Free all persist TargetID mappings for
   devices not currently present.
   MPI_SAS_OP_CLEAR_ALL_PERSISTENT - Clear al persist TargetID mappings
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   Don't use not this function during interrupt time.
   </para><para>

   Returns 0 for success, non-zero error
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-raid-phys-disk-pg0">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_raid_phys_disk_pg0</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_raid_phys_disk_pg0</refname>
 <refpurpose>
     returns phys disk page zero
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_raid_phys_disk_pg0 </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>phys_disk_num</parameter></paramdef>
   <paramdef>pRaidPhysDiskPage0_t <parameter>phys_disk</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to a Adapter Structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>phys_disk_num</parameter></term>
   <listitem>
    <para>
     io unit unique phys disk num generated by the ioc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>phys_disk</parameter></term>
   <listitem>
    <para>
     requested payload data returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success
   -EFAULT if read of config page header fails or data pointer not NULL
   -ENOMEM if pci_alloc failed
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-findImVolumes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_findImVolumes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_findImVolumes</refname>
 <refpurpose>
     Identify IDs of hidden disks and RAID Volumes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_findImVolumes </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to a Adapter Strucutre
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success
   -EFAULT if read of config page header fails or data pointer not NULL
   -ENOMEM if pci_alloc failed
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_config</refname>
 <refpurpose>
     Generic function to issue config message
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_config </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>CONFIGPARMS * <parameter>pCfg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to an adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pCfg</parameter></term>
   <listitem>
    <para>
     Pointer to a configuration structure. Struct contains
     action, page address, direction, physical address
     and pointer to a configuration page header
     Page header is updated.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success
   -EPERM if not allowed due to ISR context
   -EAGAIN if no msg frames currently available
   -EFAULT for non-successful reply or no reply (timeout)
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-print-ioc-summary">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_print_ioc_summary</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_print_ioc_summary</refname>
 <refpurpose>
     Write ASCII summary of IOC to a buffer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_print_ioc_summary </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>char * <parameter>buffer</parameter></paramdef>
   <paramdef>int * <parameter>size</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
   <paramdef>int <parameter>showlan</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     Pointer to buffer where IOC summary info should be written
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Pointer to number of bytes we wrote (set by this routine)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     Offset at which to start writing in buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>showlan</parameter></term>
   <listitem>
    <para>
     Display LAN stuff?
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine writes (english readable) ASCII text, which represents
   a summary of IOC information, to a buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-HardResetHandler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_HardResetHandler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_HardResetHandler</refname>
 <refpurpose>
     Generic reset handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_HardResetHandler </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Indicates if sleep or schedule must be called.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Issues SCSI Task Management call based on input arg values.
   If TaskMgmt fails, returns associated SCSI request.
</para>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   _HardResetHandler can be invoked from an interrupt thread (timer)
   or a non-interrupt thread.  In the former, must not call <function>schedule</function>.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   A return of -1 is a FATAL error case, as it means a
   FW reload/initialization failed.
   </para><para>

   Returns 0 for SUCCESS or -1 if FAILED.
</para>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptbase.c -->
<refentry id="API-mpt-interrupt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_interrupt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_interrupt</refname>
 <refpurpose>
  MPT adapter (IOC) specific interrupt handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>irqreturn_t <function>mpt_interrupt </function></funcdef>
   <paramdef>int <parameter>irq</parameter></paramdef>
   <paramdef>void * <parameter>bus_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     irq number (not used)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bus_id</parameter></term>
   <listitem>
    <para>
     bus identifier cookie == pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is registered via the <function>request_irq</function> kernel API call,
   and handles all interrupts generated from a specific MPT adapter
   (also referred to as a IO Controller or IOC).
   This routine must clear the interrupt from the adapter and does
   so by reading the reply FIFO.  Multiple replies may be processed
   per single call to this routine.
   </para><para>

   This routine handles register-level access of the adapter but
   dispatches (calls) a protocol-specific callback routine to handle
   the protocol-specific details of the MPT request completion.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-base-reply">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_base_reply</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_base_reply</refname>
 <refpurpose>
     MPT base driver's callback routine
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_base_reply </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>reply</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to original MPT request frame
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reply</parameter></term>
   <listitem>
    <para>
     Pointer to MPT reply frame (NULL if TurboReply)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   MPT base driver's callback routine; all base driver
   <quote>internal</quote> request/reply processing is routed here.
   Currently used for EventNotification and EventAck handling.
   </para><para>

   Returns 1 indicating original alloc'd request frame ptr
   should be freed, or 0 if it shouldn't.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-host-page-access-control">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_host_page_access_control</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_host_page_access_control</refname>
 <refpurpose>
     control the IOC's Host Page Buffer access
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_host_page_access_control </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>access_control_value</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>access_control_value</parameter></term>
   <listitem>
    <para>
     define bits below
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides mechanism for the host driver to control the IOC's
   Host Page Buffer access.
   </para><para>

   Access Control Value - bits[15:12]
   0h Reserved
   1h Enable Access { MPI_DB_HPBAC_ENABLE_ACCESS }
   2h Disable Access { MPI_DB_HPBAC_DISABLE_ACCESS }
   3h Free Buffer { MPI_DB_HPBAC_FREE_BUFFER }
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-host-page-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_host_page_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_host_page_alloc</refname>
 <refpurpose>
     allocate system memory for the fw
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_host_page_alloc </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>pIOCInit_t <parameter>ioc_init</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to pointer to IOC adapter
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc_init</parameter></term>
   <listitem>
    <para>
     Pointer to ioc init config page
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If we already allocated memory in past, then resend the same pointer.
   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-get-product-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_get_product_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_get_product_name</refname>
 <refpurpose>
     returns product string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_get_product_name </function></funcdef>
   <paramdef>u16 <parameter>vendor</parameter></paramdef>
   <paramdef>u16 <parameter>device</parameter></paramdef>
   <paramdef>u8 <parameter>revision</parameter></paramdef>
   <paramdef>char * <parameter>prod_name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vendor</parameter></term>
   <listitem>
    <para>
     pci vendor id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     pci device id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>revision</parameter></term>
   <listitem>
    <para>
     pci revision id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prod_name</parameter></term>
   <listitem>
    <para>
     string returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns product string displayed when driver loads,
   in /proc/mpt/summary and /sysfs/class/scsi_host/host&lt;X&gt;/version_product
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-do-ioc-recovery">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_do_ioc_recovery</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_do_ioc_recovery</refname>
 <refpurpose>
     Initialize or recover MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_do_ioc_recovery </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>reason</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reason</parameter></term>
   <listitem>
    <para>
     Event word / reason
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Use schedule if CAN_SLEEP else use udelay.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine performs all the steps necessary to bring the IOC
   to a OPERATIONAL state.
   </para><para>

   This routine also pre-fetches the LAN MAC address of a Fibre Channel
   MPT adapter.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 for success
   -1 if failed to get board READY
   -2 if READY but IOCFacts Failed
   -3 if READY but PrimeIOCFifos Failed
   -4 if READY but IOCInit Failed
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-detect-bound-ports">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_detect_bound_ports</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_detect_bound_ports</refname>
 <refpurpose>
     Search for matching PCI bus/dev_function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_detect_bound_ports </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to (struct pci_dev) structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Search for PCI bus/dev_function which matches
   PCI bus/dev_function (+/-1) for newly discovered 929,
   929X, 1030 or 1035.
   </para><para>

   If match on PCI dev_function +/-1 is found, bind the two MPT adapters
   using alt_ioc pointer fields in their <constant>MPT_ADAPTER</constant> structures.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-adapter-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_adapter_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_adapter_disable</refname>
 <refpurpose>
     Disable misbehaving MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_adapter_disable </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-adapter-dispose">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_adapter_dispose</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_adapter_dispose</refname>
 <refpurpose>
     Free all resources associated with an MPT adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_adapter_dispose </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine unregisters h/w resources and frees all alloc'd memory
   associated with a MPT adapter structure.
</para>
</refsect1>
</refentry>

<refentry id="API-MptDisplayIocCapabilities">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>MptDisplayIocCapabilities</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>MptDisplayIocCapabilities</refname>
 <refpurpose>
     Disply IOC's capabilities.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>MptDisplayIocCapabilities </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-MakeIocReady">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>MakeIocReady</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>MakeIocReady</refname>
 <refpurpose>
     Get IOC to a READY state, using KickStart if needed.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>MakeIocReady </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>force</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>force</parameter></term>
   <listitem>
    <para>
     Force hard KickStart of IOC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   1 - DIAG reset and READY
   0 - READY initially OR soft reset and READY
   -1 - Any failure on KickStart
   -2 - Msg Unit Reset Failed
   -3 - IO Unit Reset Failed
   -4 - IOC owned by a PEER
</para>
</refsect1>
</refentry>

<refentry id="API-GetIocFacts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>GetIocFacts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>GetIocFacts</refname>
 <refpurpose>
     Send IOCFacts request to MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>GetIocFacts </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
   <paramdef>int <parameter>reason</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reason</parameter></term>
   <listitem>
    <para>
     If recovery, only update facts.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-GetPortFacts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>GetPortFacts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>GetPortFacts</refname>
 <refpurpose>
     Send PortFacts request to MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>GetPortFacts </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>portnum</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>portnum</parameter></term>
   <listitem>
    <para>
     Port number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-SendIocInit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>SendIocInit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>SendIocInit</refname>
 <refpurpose>
     Send IOCInit request to MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>SendIocInit </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send IOCInit followed by PortEnable to bring IOC to OPERATIONAL state.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-SendPortEnable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>SendPortEnable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>SendPortEnable</refname>
 <refpurpose>
     Send PortEnable request to MPT adapter port.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>SendPortEnable </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>portnum</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>portnum</parameter></term>
   <listitem>
    <para>
     Port number to enable
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send PortEnable to bring IOC to OPERATIONAL state.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-do-upload">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_do_upload</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_do_upload</refname>
 <refpurpose>
     Construct and Send FWUpload request to MPT adapter port.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_do_upload </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 for success, &gt;0 for handshake failure
   &lt;0 for fw upload failure.
</para>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   If bound IOC and a successful FWUpload was performed
   on the bound IOC, the second image is discarded
   and memory is free'd. Both channels must upload to prevent
   IOC from running in degraded mode.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-downloadboot">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_downloadboot</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_downloadboot</refname>
 <refpurpose>
     DownloadBoot code
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_downloadboot </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MpiFwHeader_t * <parameter>pFwHeader</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pFwHeader</parameter></term>
   <listitem>
    <para>
     Pointer to firmware header info
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   FwDownloadBoot requires Programmed IO access.
   </para><para>

   Returns 0 for success
   -1 FW Image size is 0
   -2 No valid cached_fw Pointer
   &lt;0 for fw upload failure.
</para>
</refsect1>
</refentry>

<refentry id="API-KickStart">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>KickStart</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>KickStart</refname>
 <refpurpose>
     Perform hard reset of MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>KickStart </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>force</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>force</parameter></term>
   <listitem>
    <para>
     Force hard reset
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places MPT adapter in diagnostic mode via the
   WriteSequence register, and then performs a hard reset of adapter
   via the Diagnostic register.
</para>
</refsect1>
<refsect1>
<title>Inputs</title>
<para>
   sleepflag - CAN_SLEEP (non-interrupt thread)
   or NO_SLEEP (interrupt thread, use mdelay)
   force - 1 if doorbell active, board fault state
   board operational, IOC_RECOVERY or
   IOC_BRINGUP and there is an alt_ioc.
   0 else
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   1 - hard reset, READY
   0 - no reset due to History bit, READY
   -1 - no reset due to History bit but not READY
   OR reset but failed to come READY
   -2 - no reset, could not enter DIAG mode
   -3 - reset but bad FW bit
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-diag-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_diag_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_diag_reset</refname>
 <refpurpose>
     Perform hard reset of the adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_diag_reset </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>ignore</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ignore</parameter></term>
   <listitem>
    <para>
     Set if to honor and clear to ignore
     the reset history bit
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     CAN_SLEEP if called in a non-interrupt thread,
     else set to NO_SLEEP (use mdelay instead)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places the adapter in diagnostic mode via the
   WriteSequence register and then performs a hard reset of adapter
   via the Diagnostic register. Adapter should be in ready state
   upon successful completion.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   1  hard reset successful
   0  no reset performed because reset history bit set
   -2  enabling diagnostic mode failed
   -3  diagnostic reset failed
</para>
</refsect1>
</refentry>

<refentry id="API-SendIocReset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>SendIocReset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>SendIocReset</refname>
 <refpurpose>
     Send IOCReset request to MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>SendIocReset </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>reset_type</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reset_type</parameter></term>
   <listitem>
    <para>
     reset type, expected values are
     <constant>MPI_FUNCTION_IOC_MESSAGE_UNIT_RESET</constant> or <constant>MPI_FUNCTION_IO_UNIT_RESET</constant>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send IOCReset request to the MPT adapter.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-initChainBuffers">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>initChainBuffers</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>initChainBuffers</refname>
 <refpurpose>
     Allocate memory for and initialize chain buffers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>initChainBuffers </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates memory for and initializes chain buffers,
   chain buffer control arrays and spinlock.
</para>
</refsect1>
</refentry>

<refentry id="API-PrimeIocFifos">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>PrimeIocFifos</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>PrimeIocFifos</refname>
 <refpurpose>
     Initialize IOC request and reply FIFOs.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>PrimeIocFifos </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine allocates memory for the MPT reply and request frame
   pools (if necessary), and primes the IOC reply FIFO with
   reply frames.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-handshake-req-reply-wait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_handshake_req_reply_wait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_handshake_req_reply_wait</refname>
 <refpurpose>
     Send MPT request to and receive reply
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_handshake_req_reply_wait </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>reqBytes</parameter></paramdef>
   <paramdef>u32 * <parameter>req</parameter></paramdef>
   <paramdef>int <parameter>replyBytes</parameter></paramdef>
   <paramdef>u16 * <parameter>u16reply</parameter></paramdef>
   <paramdef>int <parameter>maxwait</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reqBytes</parameter></term>
   <listitem>
    <para>
     Size of the request in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>replyBytes</parameter></term>
   <listitem>
    <para>
     Expected size of the reply in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>u16reply</parameter></term>
   <listitem>
    <para>
     Pointer to area where reply should be written
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maxwait</parameter></term>
   <listitem>
    <para>
     Max wait time for a reply (in seconds)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   from IOC via doorbell handshake method.
</para>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   It is the callers responsibility to byte-swap fields in the
   request which are greater than 1 byte in size.  It is also the
   callers responsibility to byte-swap response fields which are
   greater than 1 byte in size.
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-WaitForDoorbellAck">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>WaitForDoorbellAck</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>WaitForDoorbellAck</refname>
 <refpurpose>
     Wait for IOC doorbell handshake acknowledge
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>WaitForDoorbellAck </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>howlong</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>howlong</parameter></term>
   <listitem>
    <para>
     How long to wait (in seconds)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine waits (up to ~2 seconds max) for IOC doorbell
   handshake ACKnowledge, indicated by the IOP_DOORBELL_STATUS
   bit in its IntStatus register being clear.
   </para><para>

   Returns a negative value on failure, else wait loop count.
</para>
</refsect1>
</refentry>

<refentry id="API-WaitForDoorbellInt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>WaitForDoorbellInt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>WaitForDoorbellInt</refname>
 <refpurpose>
     Wait for IOC to set its doorbell interrupt bit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>WaitForDoorbellInt </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>howlong</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>howlong</parameter></term>
   <listitem>
    <para>
     How long to wait (in seconds)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine waits (up to ~2 seconds max) for IOC doorbell interrupt
   (MPI_HIS_DOORBELL_INTERRUPT) to be set in the IntStatus register.
   </para><para>

   Returns a negative value on failure, else wait loop count.
</para>
</refsect1>
</refentry>

<refentry id="API-WaitForDoorbellReply">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>WaitForDoorbellReply</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>WaitForDoorbellReply</refname>
 <refpurpose>
     Wait for and capture an IOC handshake reply.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>WaitForDoorbellReply </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>howlong</parameter></paramdef>
   <paramdef>int <parameter>sleepFlag</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>howlong</parameter></term>
   <listitem>
    <para>
     How long to wait (in seconds)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sleepFlag</parameter></term>
   <listitem>
    <para>
     Specifies whether the process can sleep
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine polls the IOC for a handshake reply, 16 bits at a time.
   Reply is cached to IOC private area large enough to hold a maximum
   of 128 bytes of reply data.
   </para><para>

   Returns a negative value on failure, else size of reply in WORDS.
</para>
</refsect1>
</refentry>

<refentry id="API-GetLanConfigPages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>GetLanConfigPages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>GetLanConfigPages</refname>
 <refpurpose>
     Fetch LANConfig pages.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>GetLanConfigPages </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 for success
   -ENOMEM if no memory available
   -EPERM if not allowed due to ISR context
   -EAGAIN if no msg frames currently available
   -EFAULT for non-successful reply or no reply (timeout)
</para>
</refsect1>
</refentry>

<refentry id="API-GetIoUnitPage2">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>GetIoUnitPage2</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>GetIoUnitPage2</refname>
 <refpurpose>
     Retrieve BIOS version and boot order information.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>GetIoUnitPage2 </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 for success
   -ENOMEM if no memory available
   -EPERM if not allowed due to ISR context
   -EAGAIN if no msg frames currently available
   -EFAULT for non-successful reply or no reply (timeout)
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-GetScsiPortSettings">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_GetScsiPortSettings</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_GetScsiPortSettings</refname>
 <refpurpose>
     read SCSI Port Page 0 and 2
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_GetScsiPortSettings </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>portnum</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to a Adapter Strucutre
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>portnum</parameter></term>
   <listitem>
    <para>
     IOC port number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   -EFAULT if read of config page header fails
   or if no nvram
   If read of SCSI Port Page 0 fails,
   NVRAM = MPT_HOST_NVRAM_INVALID  (0xFFFFFFFF)
</para>
</refsect1>
<refsect1>
<title>Adapter settings</title>
<para>
   async, narrow
   Return 1
   If read of SCSI Port Page 2 fails,
   Adapter settings valid
   NVRAM = MPT_HOST_NVRAM_INVALID  (0xFFFFFFFF)
   Return 1
   Else
   Both valid
   Return 0
   CHECK - what type of locking mechanisms should be used????
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-readScsiDevicePageHeaders">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_readScsiDevicePageHeaders</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_readScsiDevicePageHeaders</refname>
 <refpurpose>
     save version and length of SDP1
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_readScsiDevicePageHeaders </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>portnum</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to a Adapter Strucutre
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>portnum</parameter></term>
   <listitem>
    <para>
     IOC port number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   -EFAULT if read of config page header fails
   or 0 if success.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-inactive-raid-list-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_inactive_raid_list_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_inactive_raid_list_free</refname>
 <refpurpose>
     This clears this link list.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_inactive_raid_list_free </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     pointer to per adapter structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-inactive-raid-volumes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_inactive_raid_volumes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_inactive_raid_volumes</refname>
 <refpurpose>
     sets up link list of phy_disk_nums for devices belonging in an inactive volume
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_inactive_raid_volumes </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>channel</parameter></paramdef>
   <paramdef>u8 <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     pointer to per adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>channel</parameter></term>
   <listitem>
    <para>
     volume channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     volume target id
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para>
</refsect1>
</refentry>

<refentry id="API-SendEventNotification">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>SendEventNotification</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>SendEventNotification</refname>
 <refpurpose>
     Send EventNotification (on or off) request to adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>SendEventNotification </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u8 <parameter>EvSwitch</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>EvSwitch</parameter></term>
   <listitem>
    <para>
     Event switch flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-SendEventAck">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>SendEventAck</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>SendEventAck</refname>
 <refpurpose>
     Send EventAck request to MPT adapter.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>SendEventAck </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>EventNotificationReply_t * <parameter>evnp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>evnp</parameter></term>
   <listitem>
    <para>
     Pointer to original EventNotification request
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mpt-timer-expired">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_timer_expired</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_timer_expired</refname>
 <refpurpose>
     Callback for timer process.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_timer_expired </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>
     Pointer to MPT_SCSI_HOST recast as an unsigned long
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Used only internal config functionality.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-ioc-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_ioc_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_ioc_reset</refname>
 <refpurpose>
     Base cleanup for hard reset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mpt_ioc_reset </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>reset_phase</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to the adapter structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reset_phase</parameter></term>
   <listitem>
    <para>
     Indicates pre- or post-reset functionality
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   Frees resources with internally generated commands.
</para>
</refsect1>
</refentry>

<refentry id="API-procmpt-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>procmpt_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>procmpt_create</refname>
 <refpurpose>
     Create <constant>MPT_PROCFS_MPTBASEDIR</constant> entries.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>procmpt_create </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-procmpt-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>procmpt_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>procmpt_destroy</refname>
 <refpurpose>
     Tear down <constant>MPT_PROCFS_MPTBASEDIR</constant> entries.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>procmpt_destroy </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-procmpt-summary-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>procmpt_summary_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>procmpt_summary_read</refname>
 <refpurpose>
     Handle read request of a summary file
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>procmpt_summary_read </function></funcdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>char ** <parameter>start</parameter></paramdef>
   <paramdef>off_t <parameter>offset</parameter></paramdef>
   <paramdef>int <parameter>request</parameter></paramdef>
   <paramdef>int * <parameter>eof</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     Pointer to area to write information
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Pointer to start pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     Offset to start writing
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>request</parameter></term>
   <listitem>
    <para>
     Amount of read data requested
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>eof</parameter></term>
   <listitem>
    <para>
     Pointer to EOF integer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     Pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Handles read request from /proc/mpt/summary or /proc/mpt/iocN/summary.
   Returns number of characters written to process performing the read.
</para>
</refsect1>
</refentry>

<refentry id="API-procmpt-version-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>procmpt_version_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>procmpt_version_read</refname>
 <refpurpose>
     Handle read request from /proc/mpt/version.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>procmpt_version_read </function></funcdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>char ** <parameter>start</parameter></paramdef>
   <paramdef>off_t <parameter>offset</parameter></paramdef>
   <paramdef>int <parameter>request</parameter></paramdef>
   <paramdef>int * <parameter>eof</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     Pointer to area to write information
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Pointer to start pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     Offset to start writing
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>request</parameter></term>
   <listitem>
    <para>
     Amount of read data requested
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>eof</parameter></term>
   <listitem>
    <para>
     Pointer to EOF integer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     Pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns number of characters written to process performing the read.
</para>
</refsect1>
</refentry>

<refentry id="API-procmpt-iocinfo-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>procmpt_iocinfo_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>procmpt_iocinfo_read</refname>
 <refpurpose>
     Handle read request from /proc/mpt/iocN/info.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>procmpt_iocinfo_read </function></funcdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
   <paramdef>char ** <parameter>start</parameter></paramdef>
   <paramdef>off_t <parameter>offset</parameter></paramdef>
   <paramdef>int <parameter>request</parameter></paramdef>
   <paramdef>int * <parameter>eof</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     Pointer to area to write information
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Pointer to start pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     Offset to start writing
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>request</parameter></term>
   <listitem>
    <para>
     Amount of read data requested
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>eof</parameter></term>
   <listitem>
    <para>
     Pointer to EOF integer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     Pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns number of characters written to process performing the read.
</para>
</refsect1>
</refentry>

<refentry id="API-ProcessEventNotification">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>ProcessEventNotification</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>ProcessEventNotification</refname>
 <refpurpose>
     Route EventNotificationReply to all event handlers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>ProcessEventNotification </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>EventNotificationReply_t * <parameter>pEventReply</parameter></paramdef>
   <paramdef>int * <parameter>evHandlers</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pEventReply</parameter></term>
   <listitem>
    <para>
     Pointer to EventNotification reply frame
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>evHandlers</parameter></term>
   <listitem>
    <para>
     Pointer to integer, number of event handlers
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Routes a received EventNotificationReply to all currently registered
   event handlers.
   Returns sum of event handlers return values.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-fc-log-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_fc_log_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_fc_log_info</refname>
 <refpurpose>
     Log information returned from Fibre Channel IOC.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_fc_log_info </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>log_info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>log_info</parameter></term>
   <listitem>
    <para>
     U32 LogInfo reply word from the IOC
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refer to lsi/mpi_log_fc.h.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-spi-log-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_spi_log_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_spi_log_info</refname>
 <refpurpose>
     Log information returned from SCSI Parallel IOC.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_spi_log_info </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>log_info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>log_info</parameter></term>
   <listitem>
    <para>
     U32 LogInfo word from the IOC
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refer to lsi/sp_log.h.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-sas-log-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_sas_log_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_sas_log_info</refname>
 <refpurpose>
     Log information returned from SAS IOC.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_sas_log_info </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>log_info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>log_info</parameter></term>
   <listitem>
    <para>
     U32 LogInfo reply word from the IOC
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refer to lsi/mpi_log_sas.h.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-iocstatus-info-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_iocstatus_info_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_iocstatus_info_config</refname>
 <refpurpose>
     IOCSTATUS information for config pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_iocstatus_info_config </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>ioc_status</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc_status</parameter></term>
   <listitem>
    <para>
     U32 IOCStatus word from IOC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refer to lsi/mpi.h.
</para>
</refsect1>
</refentry>

<refentry id="API-mpt-iocstatus-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mpt_iocstatus_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mpt_iocstatus_info</refname>
 <refpurpose>
     IOCSTATUS information returned from IOC.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mpt_iocstatus_info </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>u32 <parameter>ioc_status</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ioc_status</parameter></term>
   <listitem>
    <para>
     U32 IOCStatus word from IOC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to MPT request frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refer to lsi/mpi.h.
</para>
</refsect1>
</refentry>

<refentry id="API-fusion-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fusion_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fusion_init</refname>
 <refpurpose>
     Fusion MPT base driver initialization routine.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>fusion_init </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-fusion-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fusion_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fusion_exit</refname>
 <refpurpose>
     Perform driver unload cleanup.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>fusion_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   This routine frees all resources associated with each MPT adapter
   and removes all <constant>MPT_PROCFS_MPTBASEDIR</constant> entries.
</para>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptscsih.c -->
<refentry id="API-mptscsih-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_info</refname>
 <refpurpose>
  Return information about MPT adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>mptscsih_info </function></funcdef>
   <paramdef>struct Scsi_Host * <parameter>SChost</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SChost</parameter></term>
   <listitem>
    <para>
     Pointer to Scsi_Host structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.info routine)
   </para><para>

   Returns pointer to buffer where information was written.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-proc-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_proc_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_proc_info</refname>
 <refpurpose>
     Return information about MPT adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_proc_info </function></funcdef>
   <paramdef>struct Scsi_Host * <parameter>host</parameter></paramdef>
   <paramdef>char * <parameter>buffer</parameter></paramdef>
   <paramdef>char ** <parameter>start</parameter></paramdef>
   <paramdef>off_t <parameter>offset</parameter></paramdef>
   <paramdef>int <parameter>length</parameter></paramdef>
   <paramdef>int <parameter>func</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>host</parameter></term>
   <listitem>
    <para>
     scsi host struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     if write, user data; if read, buffer for user
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     returns the buffer address
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     if write, 0; if read, the current offset into the buffer from
     the previous read.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     if write, return length;
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>func</parameter></term>
   <listitem>
    <para>
     write = 1; read = 0
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.info routine)
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-qcmd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_qcmd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_qcmd</refname>
 <refpurpose>
     Primary Fusion MPT SCSI initiator IO start routine.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_qcmd </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
   <paramdef>void (*<parameter>done</parameter>)
     <funcparams>struct scsi_cmnd *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     Pointer to scsi_cmnd structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>done</parameter></term>
   <listitem>
    <para>
     Pointer SCSI mid-layer IO completion function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.queuecommand routine)
   This is the primary SCSI IO start routine.  Create a MPI SCSIIORequest
   from a linux scsi_cmnd request and send it to the IOC.
   </para><para>

   Returns 0. (rtn value discarded by linux scsi mid-layer)
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-TMHandler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_TMHandler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_TMHandler</refname>
 <refpurpose>
     Generic handler for SCSI Task Management.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_TMHandler </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>u8 <parameter>type</parameter></paramdef>
   <paramdef>u8 <parameter>channel</parameter></paramdef>
   <paramdef>u8 <parameter>id</parameter></paramdef>
   <paramdef>int <parameter>lun</parameter></paramdef>
   <paramdef>int <parameter>ctx2abort</parameter></paramdef>
   <paramdef>ulong <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to MPT SCSI HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     Task Management type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>channel</parameter></term>
   <listitem>
    <para>
     channel number for task management
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     Logical Target ID for reset (if appropriate)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lun</parameter></term>
   <listitem>
    <para>
     Logical Unit for reset (if appropriate)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ctx2abort</parameter></term>
   <listitem>
    <para>
     Context for the task to be aborted (if appropriate)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     timeout for task management control
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Fall through to mpt_HardResetHandler if</title>
<para>
   not operational, too many
   failed TM requests or handshake failure.
</para>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   With old EH code, at most 1 SCSI TaskMgmt function per IOC
   will be active.
   </para><para>

   Returns 0 for SUCCESS, or <constant>FAILED</constant>.
</para>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   With old EH code, at most 1 SCSI TaskMgmt function per IOC
   will be active.
   </para><para>

   Returns 0 for SUCCESS, or <constant>FAILED</constant>.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-abort">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_abort</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_abort</refname>
 <refpurpose>
     Abort linux scsi_cmnd routine, new_eh variant
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_abort </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     Pointer to scsi_cmnd structure, IO to be aborted
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.eh_abort_handler routine)
   </para><para>

   Returns SUCCESS or FAILED.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-dev-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_dev_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_dev_reset</refname>
 <refpurpose>
     Perform a SCSI TARGET_RESET!  new_eh variant
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_dev_reset </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     Pointer to scsi_cmnd structure, IO which reset is due to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.eh_dev_reset_handler routine)
   </para><para>

   Returns SUCCESS or FAILED.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-bus-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_bus_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_bus_reset</refname>
 <refpurpose>
     Perform a SCSI BUS_RESET!	new_eh variant
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_bus_reset </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     Pointer to scsi_cmnd structure, IO which reset is due to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.eh_bus_reset_handler routine)
   </para><para>

   Returns SUCCESS or FAILED.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-host-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_host_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_host_reset</refname>
 <refpurpose>
     Perform a SCSI host adapter RESET (new_eh variant)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_host_reset </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     Pointer to scsi_cmnd structure, IO which reset is due to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   (linux scsi_host_template.eh_host_reset_handler routine)
   </para><para>

   Returns SUCCESS or FAILED.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-taskmgmt-complete">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_taskmgmt_complete</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_taskmgmt_complete</refname>
 <refpurpose>
     Registered with Fusion MPT base driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_taskmgmt_complete </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to SCSI task mgmt request frame
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mr</parameter></term>
   <listitem>
    <para>
     Pointer to SCSI task mgmt reply frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is called from mptbase.c::<function>mpt_interrupt</function> at the completion
   of any SCSI task management request.
   This routine is registered with the MPT (base) driver at driver
   load/init time via the <function>mpt_register</function> API call.
   </para><para>

   Returns 1 indicating alloc'd request frame ptr should be freed.
</para>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptscsih.c -->
<refentry id="API-mptscsih-add-sge">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_add_sge</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_add_sge</refname>
 <refpurpose>
  Place a simple SGE at address pAddr.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptscsih_add_sge </function></funcdef>
   <paramdef>char * <parameter>pAddr</parameter></paramdef>
   <paramdef>u32 <parameter>flagslength</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>dma_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pAddr</parameter></term>
   <listitem>
    <para>
     virtual address for SGE
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flagslength</parameter></term>
   <listitem>
    <para>
     SGE flags and data transfer length
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_addr</parameter></term>
   <listitem>
    <para>
     Physical address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places a MPT request frame back on the MPT adapter's
   FreeQ.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-add-chain">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_add_chain</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_add_chain</refname>
 <refpurpose>
     Place a chain SGE at address pAddr.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptscsih_add_chain </function></funcdef>
   <paramdef>char * <parameter>pAddr</parameter></paramdef>
   <paramdef>u8 <parameter>next</parameter></paramdef>
   <paramdef>u16 <parameter>length</parameter></paramdef>
   <paramdef>dma_addr_t <parameter>dma_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pAddr</parameter></term>
   <listitem>
    <para>
     virtual address for SGE
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>next</parameter></term>
   <listitem>
    <para>
     nextChainOffset value (u32's)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     length of next SGL segment
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_addr</parameter></term>
   <listitem>
    <para>
     Physical address
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine places a MPT request frame back on the MPT adapter's
   FreeQ.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-info-scsiio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_info_scsiio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_info_scsiio</refname>
 <refpurpose>
     debug print info on reply frame
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptscsih_info_scsiio </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>struct scsi_cmnd * <parameter>sc</parameter></paramdef>
   <paramdef>SCSIIOReply_t * <parameter>pScsiReply</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sc</parameter></term>
   <listitem>
    <para>
     original scsi cmnd pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pScsiReply</parameter></term>
   <listitem>
    <para>
     Pointer to MPT reply frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   MPT_DEBUG_REPLY needs to be enabled to obtain this info
   </para><para>

   Refer to lsi/mpi.h.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-IssueTaskMgmt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_IssueTaskMgmt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_IssueTaskMgmt</refname>
 <refpurpose>
     Generic send Task Management function.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_IssueTaskMgmt </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>u8 <parameter>type</parameter></paramdef>
   <paramdef>u8 <parameter>channel</parameter></paramdef>
   <paramdef>u8 <parameter>id</parameter></paramdef>
   <paramdef>int <parameter>lun</parameter></paramdef>
   <paramdef>int <parameter>ctx2abort</parameter></paramdef>
   <paramdef>ulong <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_SCSI_HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     Task Management type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>channel</parameter></term>
   <listitem>
    <para>
     channel number for task management
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     Logical Target ID for reset (if appropriate)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>lun</parameter></term>
   <listitem>
    <para>
     Logical Unit for reset (if appropriate)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ctx2abort</parameter></term>
   <listitem>
    <para>
     Context for the task to be aborted (if appropriate)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     timeout for task management control
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   _HardResetHandler can be invoked from an interrupt thread (timer)
   or a non-interrupt thread.  In the former, must not call <function>schedule</function>.
   </para><para>

   Not all fields are meaningfull for all task types.
   </para><para>

   Returns 0 for SUCCESS, or FAILED.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-tm-pending-wait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_tm_pending_wait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_tm_pending_wait</refname>
 <refpurpose>
     wait for pending task management request to complete
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_tm_pending_wait </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to MPT host structure.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns {SUCCESS,FAILED}.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-tm-wait-for-completion">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_tm_wait_for_completion</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_tm_wait_for_completion</refname>
 <refpurpose>
     wait for completion of TM task
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_tm_wait_for_completion </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>ulong <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to MPT host structure.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     timeout value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns {SUCCESS,FAILED}.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-do-cmd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_do_cmd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_do_cmd</refname>
 <refpurpose>
     Do internal command.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptscsih_do_cmd </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>INTERNAL_CMD * <parameter>io</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     MPT_SCSI_HOST pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>io</parameter></term>
   <listitem>
    <para>
     INTERNAL_CMD pointer.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Issue the specified internally generated command and do command
   specific cleanup. For bus scan / DV only.
</para>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   If command is Inquiry and status is good,
   initialize a target structure, save the data
</para>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   Single threaded access only.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   &lt; 0 if an illegal command or no resources
   </para><para>

   0 if good
   </para><para>

   &gt; 0 if command complete but some type of completion error.
</para>
</refsect1>
</refentry>

<refentry id="API-mptscsih-synchronize-cache">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptscsih_synchronize_cache</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptscsih_synchronize_cache</refname>
 <refpurpose>
     Send SYNCHRONIZE_CACHE to all disks.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptscsih_synchronize_cache </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>VirtDevice * <parameter>vdevice</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vdevice</parameter></term>
   <listitem>
    <para>
     virtual target device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Uses the ISR, but with special processing.
   MUST be single-threaded.
</para>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptctl.c -->
<refentry id="API-mptctl-syscall-down">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptctl_syscall_down</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptctl_syscall_down</refname>
 <refpurpose>
  Down the MPT adapter syscall semaphore.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptctl_syscall_down </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>int <parameter>nonblock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT adapter
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nonblock</parameter></term>
   <listitem>
    <para>
     boolean, non-zero if O_NONBLOCK is set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   All of the ioctl commands can potentially sleep, which is illegal
   with a spinlock held, thus we perform mutual exclusion here.
   </para><para>

   Returns negative errno on error, or zero for success.
</para>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptspi.c -->
<refentry id="API-mptspi-setTargetNegoParms">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_setTargetNegoParms</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_setTargetNegoParms</refname>
 <refpurpose>
  Update the target negotiation parameters
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptspi_setTargetNegoParms </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>VirtTarget * <parameter>target</parameter></paramdef>
   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI Host Structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>target</parameter></term>
   <listitem>
    <para>
     per target private data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sdev</parameter></term>
   <listitem>
    <para>
     SCSI device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Update the target negotiation parameters based on the the Inquiry
   data, adapter capabilities, and NVRAM settings.
</para>
</refsect1>
</refentry>

<refentry id="API-mptspi-writeIOCPage4">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_writeIOCPage4</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_writeIOCPage4</refname>
 <refpurpose>
     write IOC Page 4
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptspi_writeIOCPage4 </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>u8 <parameter>channel</parameter></paramdef>
   <paramdef>u8 <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI Host Structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>channel</parameter></term>
   <listitem>
    <para>
     channel number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     write IOC Page4 for this ID &amp; Bus
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   -EAGAIN if unable to obtain a Message Frame
   or 0 if success.
</para>
</refsect1>
<refsect1>
<title>Remark</title>
<para>
   We do not wait for a return, write pages sequentially.
</para>
</refsect1>
</refentry>

<refentry id="API-mptspi-initTarget">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_initTarget</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_initTarget</refname>
 <refpurpose>
     Target, LUN alloc/free functionality.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptspi_initTarget </function></funcdef>
   <paramdef>MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>VirtTarget * <parameter>vtarget</parameter></paramdef>
   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_SCSI_HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vtarget</parameter></term>
   <listitem>
    <para>
     per target private data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sdev</parameter></term>
   <listitem>
    <para>
     SCSI device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   It's only SAFE to call this routine if data points to
   sane &amp; valid STANDARD INQUIRY data!
   </para><para>

   Allocate and initialize memory for this target.
   Save inquiry data.
</para>
</refsect1>
</refentry>

<refentry id="API-mptspi-is-raid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_is_raid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_is_raid</refname>
 <refpurpose>
     Determines whether target is belonging to volume
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mptspi_is_raid </function></funcdef>
   <paramdef>struct _MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>u32 <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     target device id
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   non-zero = true
   zero = false
</para>
</refsect1>
</refentry>

<refentry id="API-mptspi-print-write-nego">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_print_write_nego</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_print_write_nego</refname>
 <refpurpose>
     negotiation parameters debug info that is being sent
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptspi_print_write_nego </function></funcdef>
   <paramdef>struct _MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>struct scsi_target * <parameter>starget</parameter></paramdef>
   <paramdef>u32 <parameter>ii</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>starget</parameter></term>
   <listitem>
    <para>
     SCSI target
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ii</parameter></term>
   <listitem>
    <para>
     negotiation parameters
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mptspi-print-read-nego">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_print_read_nego</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_print_read_nego</refname>
 <refpurpose>
     negotiation parameters debug info that is being read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mptspi_print_read_nego </function></funcdef>
   <paramdef>struct _MPT_SCSI_HOST * <parameter>hd</parameter></paramdef>
   <paramdef>struct scsi_target * <parameter>starget</parameter></paramdef>
   <paramdef>u32 <parameter>ii</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hd</parameter></term>
   <listitem>
    <para>
     Pointer to a SCSI HOST structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>starget</parameter></term>
   <listitem>
    <para>
     SCSI target
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ii</parameter></term>
   <listitem>
    <para>
     negotiation parameters
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mptspi-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_init</refname>
 <refpurpose>
     Register MPT adapter(s) as SCSI host(s) with SCSI mid-layer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>mptspi_init </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mptspi-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptspi_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptspi_exit</refname>
 <refpurpose>
     Unregisters MPT adapter(s)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>mptspi_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptfc.c -->
<refentry id="API-mptfc-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptfc_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptfc_init</refname>
 <refpurpose>
  Register MPT adapter(s) as SCSI host(s) with SCSI mid-layer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>mptfc_init </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns 0 for success, non-zero for failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mptfc-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptfc_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptfc_remove</refname>
 <refpurpose>
     Remove fc infrastructure for devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __devexit <function>mptfc_remove </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     Pointer to pci_dev structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mptfc-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mptfc_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mptfc_exit</refname>
 <refpurpose>
     Unregisters MPT adapter(s)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>mptfc_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para>
</refsect1>
</refentry>

<!-- drivers/message/fusion/mptlan.c -->
<refentry id="API-lan-reply">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>lan_reply</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>lan_reply</refname>
 <refpurpose>
  Handle all data sent from the hardware.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>lan_reply </function></funcdef>
   <paramdef>MPT_ADAPTER * <parameter>ioc</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>mf</parameter></paramdef>
   <paramdef>MPT_FRAME_HDR * <parameter>reply</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ioc</parameter></term>
   <listitem>
    <para>
     Pointer to MPT_ADAPTER structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mf</parameter></term>
   <listitem>
    <para>
     Pointer to original MPT request frame (NULL if TurboReply)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reply</parameter></term>
   <listitem>
    <para>
     Pointer to MPT reply frame
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 1 indicating original alloc'd request frame ptr
   should be freed, or 0 if it shouldn't.
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>I2O message devices</title>
<!-- include/linux/i2o.h -->
<refentry id="API-i2o-sg-tablesize">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_sg_tablesize</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_sg_tablesize</refname>
 <refpurpose>
  Calculate the maximum number of elements in a SGL
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u16 <function>i2o_sg_tablesize </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u16 <parameter>body_size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller for which the calculation should be done
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>body_size</parameter></term>
   <listitem>
    <para>
     maximum body size used for message in 32-bit words.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return the maximum number of SG elements in a SG list.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-dma-map-single">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_dma_map_single</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_dma_map_single</refname>
 <refpurpose>
     Map pointer to controller and fill in I2O message.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>dma_addr_t <function>i2o_dma_map_single </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>void * <parameter>ptr</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>enum dma_data_direction <parameter>direction</parameter></paramdef>
   <paramdef>u32 ** <parameter>sg_ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer to the data which should be mapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of data in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>direction</parameter></term>
   <listitem>
    <para>
     DMA_TO_DEVICE / DMA_FROM_DEVICE
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sg_ptr</parameter></term>
   <listitem>
    <para>
     pointer to the SG list inside the I2O message
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function does all necessary DMA handling and also writes the I2O
   SGL elements into the I2O message. For details on DMA handling see also
   <function>dma_map_single</function>. The pointer sg_ptr will only be set to the end of the
   SG list if the allocation was successful.
   </para><para>

   Returns DMA address which must be checked for failures using
   <function>dma_mapping_error</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-dma-map-sg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_dma_map_sg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_dma_map_sg</refname>
 <refpurpose>
     Map a SG List to controller and fill in I2O message.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_dma_map_sg </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>struct scatterlist * <parameter>sg</parameter></paramdef>
   <paramdef>int <parameter>sg_count</parameter></paramdef>
   <paramdef>enum dma_data_direction <parameter>direction</parameter></paramdef>
   <paramdef>u32 ** <parameter>sg_ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sg</parameter></term>
   <listitem>
    <para>
     SG list to be mapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sg_count</parameter></term>
   <listitem>
    <para>
     number of elements in the SG list
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>direction</parameter></term>
   <listitem>
    <para>
     DMA_TO_DEVICE / DMA_FROM_DEVICE
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sg_ptr</parameter></term>
   <listitem>
    <para>
     pointer to the SG list inside the I2O message
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function does all necessary DMA handling and also writes the I2O
   SGL elements into the I2O message. For details on DMA handling see also
   <function>dma_map_sg</function>. The pointer sg_ptr will only be set to the end of the SG
   list if the allocation was successful.
   </para><para>

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

<refentry id="API-i2o-dma-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_dma_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_dma_alloc</refname>
 <refpurpose>
     Allocate DMA memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_dma_alloc </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct i2o_dma * <parameter>addr</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     struct device pointer to the PCI device of the I2O controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     i2o_dma struct which should get the DMA buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of the new DMA memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     GFP mask
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a coherent DMA memory and write the pointers into addr.
   </para><para>

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

<refentry id="API-i2o-dma-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_dma_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_dma_free</refname>
 <refpurpose>
     Free DMA memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_dma_free </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct i2o_dma * <parameter>addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     struct device pointer to the PCI device of the I2O controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     i2o_dma struct which contains the DMA buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free a coherent DMA memory and set virtual address of addr to NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-dma-realloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_dma_realloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_dma_realloc</refname>
 <refpurpose>
     Realloc DMA memory
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_dma_realloc </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct i2o_dma * <parameter>addr</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     struct device pointer to the PCI device of the I2O controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     pointer to a i2o_dma struct DMA buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     new length of memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_mask</parameter></term>
   <listitem>
    <para>
     GFP mask
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If there was something allocated in the addr, free it first. If len &gt; 0
   than try to allocate it and write the addresses back to the addr
   structure. If len == 0 set the virtual address to NULL.
   </para><para>

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

<refentry id="API-i2o-driver-notify-controller-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_driver_notify_controller_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_driver_notify_controller_add</refname>
 <refpurpose>
     Send notification of added controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_driver_notify_controller_add </function></funcdef>
   <paramdef>struct i2o_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     I2O driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send notification of added controller to a single registered driver.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-driver-notify-controller-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_driver_notify_controller_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_driver_notify_controller_remove</refname>
 <refpurpose>
     Send notification of removed controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_driver_notify_controller_remove </function></funcdef>
   <paramdef>struct i2o_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     I2O driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send notification of removed controller to a single registered driver.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-driver-notify-device-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_driver_notify_device_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_driver_notify_device_add</refname>
 <refpurpose>
     Send notification of added device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_driver_notify_device_add </function></funcdef>
   <paramdef>struct i2o_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct i2o_device * <parameter>i2o_dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     I2O driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>i2o_dev</parameter></term>
   <listitem>
    <para>
     the added i2o_device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send notification of added device to a single registered driver.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-driver-notify-device-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_driver_notify_device_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_driver_notify_device_remove</refname>
 <refpurpose>
     Send notification of removed device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_driver_notify_device_remove </function></funcdef>
   <paramdef>struct i2o_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct i2o_device * <parameter>i2o_dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     I2O driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>i2o_dev</parameter></term>
   <listitem>
    <para>
     the added i2o_device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send notification of removed device to a single registered driver.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-msg-out-to-virt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_msg_out_to_virt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_msg_out_to_virt</refname>
 <refpurpose>
     Turn an I2O message to a virtual address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_message * <function>i2o_msg_out_to_virt </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u32 <parameter>m</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     message engine value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Turn a receive message from an I2O controller bus address into
   a Linux virtual address. The shared page frame is a linear block
   so we simply have to shift the offset. This function does not
   work for sender side messages as they are ioremap objects
   provided by the I2O controller.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-msg-in-to-virt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_msg_in_to_virt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_msg_in_to_virt</refname>
 <refpurpose>
     Turn an I2O message to a virtual address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_message __iomem * <function>i2o_msg_in_to_virt </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u32 <parameter>m</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     message engine value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Turn a send message from an I2O controller bus address into
   a Linux virtual address. The shared page frame is a linear block
   so we simply have to shift the offset. This function does not
   work for receive side messages as they are kmalloc objects
   in a different pool.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-msg-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_msg_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_msg_get</refname>
 <refpurpose>
     obtain an I2O message from the IOP
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_message * <function>i2o_msg_get </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function tries to get a message frame. If no message frame is
   available do not wait until one is availabe (see also i2o_msg_get_wait).
   The returned pointer to the message frame is not in I/O memory, it is
   allocated from a mempool. But because a MFA is allocated from the
   controller too it is guaranteed that <function>i2o_msg_post</function> will never fail.
   </para><para>

   On a success a pointer to the message frame is returned. If the message
   queue is empty -EBUSY is returned and if no memory is available -ENOMEM
   is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-msg-post">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_msg_post</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_msg_post</refname>
 <refpurpose>
     Post I2O message to I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_msg_post </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>struct i2o_message * <parameter>msg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller to which the message should be send
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     message returned by <function>i2o_msg_get</function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Post the message to the I2O controller and return immediately.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-msg-post-wait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_msg_post_wait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_msg_post_wait</refname>
 <refpurpose>
     Post and wait a message and wait until return
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_msg_post_wait </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>struct i2o_message * <parameter>msg</parameter></paramdef>
   <paramdef>unsigned long <parameter>timeout</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     message to post
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     time in seconds to wait
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This API allows an OSM to post a message and then be told whether or
   not the system received a successful reply. If the message times out
   then the value '-ETIMEDOUT' is returned.
   </para><para>

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

<refentry id="API-i2o-msg-nop-mfa">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_msg_nop_mfa</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_msg_nop_mfa</refname>
 <refpurpose>
     Returns a fetched MFA back to the controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_msg_nop_mfa </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u32 <parameter>mfa</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller from which the MFA was fetched
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mfa</parameter></term>
   <listitem>
    <para>
     MFA which should be returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function must be used for preserved messages, because <function>i2o_msg_nop</function>
   also returns the allocated memory back to the msg_pool mempool.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-msg-nop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_msg_nop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_msg_nop</refname>
 <refpurpose>
     Returns a message which is not used
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_msg_nop </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>struct i2o_message * <parameter>msg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller from which the message was created
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     message which should be returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If you fetch a message via i2o_msg_get, and can't use it, you must
   return the message with this function. Otherwise the MFA is lost as well
   as the allocated memory from the mempool.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-flush-reply">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_flush_reply</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_flush_reply</refname>
 <refpurpose>
     Flush reply from I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_flush_reply </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u32 <parameter>m</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     the message identifier
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The I2O controller must be informed that the reply message is not needed
   anymore. If you forget to flush the reply, the message frame can't be
   used by the controller anymore and is therefore lost.
</para>
</refsect1>
</refentry>

<!-- drivers/message/i2o/core.h -->
<refentry id="API-i2o-iop-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_free</refname>
 <refpurpose>
  Free the i2o_controller struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_iop_free </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/message/i2o/iop.c -->
<refentry id="API-i2o-msg-get-wait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_msg_get_wait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_msg_get_wait</refname>
 <refpurpose>
  obtain an I2O message from the IOP
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_message * <function>i2o_msg_get_wait </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>int <parameter>wait</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wait</parameter></term>
   <listitem>
    <para>
     how long to wait until timeout
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function waits up to wait seconds for a message slot to be
   available.
   </para><para>

   On a success the message is returned and the pointer to the message is
   set in msg. The returned message is the physical page frame offset
   address from the read port (see the i2o spec). If no message is
   available returns I2O_QUEUE_EMPTY and msg is leaved untouched.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-cntxt-list-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_cntxt_list_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_cntxt_list_add</refname>
 <refpurpose>
     Append a pointer to context list and return a id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>i2o_cntxt_list_add </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>void * <parameter>ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller to which the context list belong
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer to add to the context list
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Because the context field in I2O is only 32-bit large, on 64-bit the
   pointer is to large to fit in the context field. The i2o_cntxt_list
   functions therefore map pointers to context fields.
   </para><para>

   Returns context id &gt; 0 on success or 0 on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-cntxt-list-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_cntxt_list_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_cntxt_list_remove</refname>
 <refpurpose>
     Remove a pointer from the context list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>i2o_cntxt_list_remove </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>void * <parameter>ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller to which the context list belong
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer which should be removed from the context list
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes a previously added pointer from the context list and returns
   the matching context id.
   </para><para>

   Returns context id on succes or 0 on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-cntxt-list-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_cntxt_list_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_cntxt_list_get</refname>
 <refpurpose>
     Get a pointer from the context list and remove it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>i2o_cntxt_list_get </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u32 <parameter>context</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller to which the context list belong
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>context</parameter></term>
   <listitem>
    <para>
     context id to which the pointer belong
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns pointer to the matching context id on success or NULL on
   failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-cntxt-list-get-ptr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_cntxt_list_get_ptr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_cntxt_list_get_ptr</refname>
 <refpurpose>
     Get a context id from the context list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>i2o_cntxt_list_get_ptr </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>void * <parameter>ptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller to which the context list belong
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     pointer to which the context id should be fetched
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns context id which matches to the pointer on succes or 0 on
   failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-find-iop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_find_iop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_find_iop</refname>
 <refpurpose>
     Find an I2O controller by id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_controller * <function>i2o_find_iop </function></funcdef>
   <paramdef>int <parameter>unit</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>unit</parameter></term>
   <listitem>
    <para>
     unit number of the I2O controller to search for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Lookup the I2O controller on the controller list.
   </para><para>

   Returns pointer to the I2O controller on success or NULL if not found.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-iop-find-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_find_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_find_device</refname>
 <refpurpose>
     Find a I2O device on an I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_device * <function>i2o_iop_find_device </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u16 <parameter>tid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller where the I2O device hangs on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tid</parameter></term>
   <listitem>
    <para>
     TID of the I2O device to search for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Searches the devices of the I2O controller for a device with TID tid and
   returns it.
   </para><para>

   Returns a pointer to the I2O device if found, otherwise NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-status-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_status_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_status_get</refname>
 <refpurpose>
     Get the status block from the I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_status_get </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Issue a status query on the controller. This updates the attached
   status block. The status block could then be accessed through
   c-&gt;status_block.
   </para><para>

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

<refentry id="API-i2o-event-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_event_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_event_register</refname>
 <refpurpose>
     Turn on/off event notification for a I2O device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_event_register </function></funcdef>
   <paramdef>struct i2o_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct i2o_driver * <parameter>drv</parameter></paramdef>
   <paramdef>int <parameter>tcntxt</parameter></paramdef>
   <paramdef>u32 <parameter>evt_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device which should receive the event registration request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     driver which want to get notified
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>tcntxt</parameter></term>
   <listitem>
    <para>
     transaction context to use with this notifier
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>evt_mask</parameter></term>
   <listitem>
    <para>
     mask of events
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Create and posts an event registration message to the task. No reply
   is waited for, or expected. If you do not want further notifications,
   call the i2o_event_register again with a evt_mask of 0.
   </para><para>

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

<!-- drivers/message/i2o/iop.c -->
<refentry id="API-i2o-iop-quiesce">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_quiesce</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_quiesce</refname>
 <refpurpose>
  quiesce controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_iop_quiesce </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Quiesce an IOP. Causes IOP to make external operation quiescent
   (i2o 'READY' state). Internal operation of the IOP continues normally.
   </para><para>

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

<refentry id="API-i2o-iop-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_enable</refname>
 <refpurpose>
     move controller from ready to OPERATIONAL
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_iop_enable </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Enable IOP. This allows the IOP to resume external operations and
   reverses the effect of a quiesce. Returns zero or an error code if
   an error occurs.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-iop-quiesce-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_quiesce_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_quiesce_all</refname>
 <refpurpose>
     Quiesce all I2O controllers on the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_iop_quiesce_all </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>

   Quiesce all I2O controllers which are connected to the system.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-iop-enable-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_enable_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_enable_all</refname>
 <refpurpose>
     Enables all controllers on the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_iop_enable_all </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>

   Enables all I2O controllers which are connected to the system.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-iop-clear">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_clear</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_clear</refname>
 <refpurpose>
     Bring I2O controller into HOLD state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_iop_clear </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Clear an IOP to HOLD state, ie. terminate external operations, clear all
   input queues and prepare for a system restart. IOP's internal operation
   continues normally and the outbound queue is alive. The IOP is not
   expected to rebuild its LCT.
   </para><para>

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

<refentry id="API-i2o-iop-init-outbound-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_init_outbound_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_init_outbound_queue</refname>
 <refpurpose>
     setup the outbound message queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_iop_init_outbound_queue </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Clear and (re)initialize IOP's outbound queue and post the message
   frames to the IOP.
   </para><para>

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

<refentry id="API-i2o-iop-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_reset</refname>
 <refpurpose>
     reset an I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_iop_reset </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller to reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reset the IOP into INIT state and wait until IOP gets into RESET state.
   Terminate all external operations, clear IOP's inbound and outbound
   queues, terminate all DDMs, and reload the IOP's operating environment
   and all local DDMs. The IOP rebuilds its LCT.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-iop-activate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_activate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_activate</refname>
 <refpurpose>
     Bring controller up to HOLD
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_iop_activate </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function brings an I2O controller into HOLD state. The adapter
   is reset if necessary and then the queues and resource table are read.
   </para><para>

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

<refentry id="API-i2o-iop-systab-set">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_systab_set</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_systab_set</refname>
 <refpurpose>
     Set the I2O System Table of the specified IOP
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_iop_systab_set </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller to which the system table should be send
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Before the systab could be set <function>i2o_systab_build</function> must be called.
   </para><para>

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

<refentry id="API-i2o-iop-online">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_online</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_online</refname>
 <refpurpose>
     Bring a controller online into OPERATIONAL state.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_iop_online </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send the system table and enable the I2O controller.
   </para><para>

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

<refentry id="API-i2o-iop-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_remove</refname>
 <refpurpose>
     Remove the I2O controller from the I2O core
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_iop_remove </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove the I2O controller from the I2O core. If devices are attached to
   the controller remove these also and finally reset the controller.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-systab-build">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_systab_build</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_systab_build</refname>
 <refpurpose>
     Build system table
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_systab_build </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 system table contains information about all the IOPs in the system
   (duh) and is used by the Executives on the IOPs to establish peer2peer
   connections. We're not supporting peer2peer at the moment, but this
   will be needed down the road for things like lan2lan forwarding.
   </para><para>

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

<refentry id="API-i2o-parse-hrt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_parse_hrt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_parse_hrt</refname>
 <refpurpose>
     Parse the hardware resource table.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_parse_hrt </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   We don't do anything with it except dumping it (in debug mode).
   </para><para>

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

<refentry id="API-i2o-iop-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_release</refname>
 <refpurpose>
     release the memory for a I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_iop_release </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O controller which should be released
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release the allocated memory. This function is called if refcount of
   device reaches 0 automatically.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-iop-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_alloc</refname>
 <refpurpose>
     Allocate and initialize a i2o_controller struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_controller * <function>i2o_iop_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>

   Allocate the necessary memory for a i2o_controller struct and
   initialize the lists and message mempool.
   </para><para>

   Returns a pointer to the I2O controller or a negative error code on
   failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-iop-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_add</refname>
 <refpurpose>
     Initialize the I2O controller and add him to the I2O core
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_iop_add </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize the I2O controller and if no error occurs add him to the I2O
   core.
   </para><para>

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

<refentry id="API-i2o-iop-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_init</refname>
 <refpurpose>
     I2O main initialization function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>i2o_iop_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>

   Initialize the I2O drivers (OSM) functions, register the Executive OSM,
   initialize the I2O PCI part and finally initialize I2O device stuff.
   </para><para>

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

<refentry id="API-i2o-iop-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_iop_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_iop_exit</refname>
 <refpurpose>
     I2O main exit function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>i2o_iop_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Removes I2O controllers from PCI subsystem and shut down OSMs.
</para>
</refsect1>
</refentry>

<!-- drivers/message/i2o/config-osm.c -->
<refentry id="API-i2o-config-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_config_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_config_init</refname>
 <refpurpose>
  Configuration OSM initialization function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>i2o_config_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>

   Registers Configuration OSM in the I2O core and if old ioctl's are
   compiled in initialize them.
   </para><para>

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

<refentry id="API-i2o-config-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_config_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_config_exit</refname>
 <refpurpose>
     Configuration OSM exit function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_config_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   If old ioctl's are compiled in exit remove them and unregisters
   Configuration OSM from I2O core.
</para>
</refsect1>
</refentry>

<!-- drivers/message/i2o/exec-osm.c -->
<refentry id="API-i2o-msg-post-wait-mem">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_msg_post_wait_mem</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_msg_post_wait_mem</refname>
 <refpurpose>
  Post and wait a message with DMA buffers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_msg_post_wait_mem </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>struct i2o_message * <parameter>msg</parameter></paramdef>
   <paramdef>unsigned long <parameter>timeout</parameter></paramdef>
   <paramdef>struct i2o_dma * <parameter>dma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     message to post
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>timeout</parameter></term>
   <listitem>
    <para>
     time in seconds to wait
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma</parameter></term>
   <listitem>
    <para>
     i2o_dma struct of the DMA buffer to free on failure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This API allows an OSM to post a message and then be told whether or
   not the system received a successful reply. If the message times out
   then the value '-ETIMEDOUT' is returned. This is a special case. In
   this situation the message may (should) complete at an indefinite time
   in the future. When it completes it will use the memory buffer
   attached to the request. If -ETIMEDOUT is returned then the memory
   buffer must not be freed. Instead the event completion will free them
   for you. In all other cases the buffer are your problem.
   </para><para>

   Returns 0 on success, negative error code on timeout or positive error
   code from reply.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-exec-lct-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_lct_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_lct_get</refname>
 <refpurpose>
     Get the IOP's Logical Configuration Table
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_exec_lct_get </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller from which the LCT should be fetched
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send a LCT NOTIFY request to the controller, and wait
   I2O_TIMEOUT_LCT_GET seconds until arrival of response. If the LCT is
   to large, retry it.
   </para><para>

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

<!-- drivers/message/i2o/exec-osm.c -->
<refentry id="API-i2o-exec-wait-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_wait_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_wait_alloc</refname>
 <refpurpose>
  Allocate a i2o_exec_wait struct an initialize it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_exec_wait * <function>i2o_exec_wait_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>

   Allocate the i2o_exec_wait struct and initialize the wait.
   </para><para>

   Returns i2o_exec_wait pointer on success or negative error code on
   failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-exec-wait-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_wait_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_wait_free</refname>
 <refpurpose>
     Free an i2o_exec_wait struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_exec_wait_free </function></funcdef>
   <paramdef>struct i2o_exec_wait * <parameter>wait</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>wait</parameter></term>
   <listitem>
    <para>
     I2O wait data which should be cleaned up
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-i2o-msg-post-wait-complete">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_msg_post_wait_complete</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_msg_post_wait_complete</refname>
 <refpurpose>
     Reply to a i2o_msg_post request from IOP
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_msg_post_wait_complete </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u32 <parameter>m</parameter></paramdef>
   <paramdef>struct i2o_message * <parameter>msg</parameter></paramdef>
   <paramdef>u32 <parameter>context</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller which answers
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     message id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     pointer to the I2O reply message
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>context</parameter></term>
   <listitem>
    <para>
     transaction context of request
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is called in interrupt context only. If the reply reached
   before the timeout, the i2o_exec_wait struct is filled with the message
   and the task will be waked up. The task is now responsible for returning
   the message m back to the controller! If the message reaches us after
   the timeout clean up the i2o_exec_wait struct (including allocated
   DMA buffer).
   </para><para>

   Return 0 on success and if the message m should not be given back to the
   I2O controller, or &gt;0 on success and if the message should be given back
   afterwords. Returns negative error code on failure. In this case the
   message must also be given back to the controller.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-exec-show-vendor-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_show_vendor_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_show_vendor_id</refname>
 <refpurpose>
     Displays Vendor ID of controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>i2o_exec_show_vendor_id </function></funcdef>
   <paramdef>struct device * <parameter>d</parameter></paramdef>
   <paramdef>struct device_attribute * <parameter>attr</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>d</parameter></term>
   <listitem>
    <para>
     device of which the Vendor ID should be displayed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     device_attribute to display
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     buffer into which the Vendor ID should be printed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns number of bytes printed into buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-exec-show-product-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_show_product_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_show_product_id</refname>
 <refpurpose>
     Displays Product ID of controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>i2o_exec_show_product_id </function></funcdef>
   <paramdef>struct device * <parameter>d</parameter></paramdef>
   <paramdef>struct device_attribute * <parameter>attr</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>d</parameter></term>
   <listitem>
    <para>
     device of which the Product ID should be displayed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     device_attribute to display
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     buffer into which the Product ID should be printed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns number of bytes printed into buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-exec-probe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_probe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_probe</refname>
 <refpurpose>
     Called if a new I2O device (executive class) appears
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_exec_probe </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device which should be probed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers event notification for every event from Executive device. The
   return is always 0, because we want all devices of class Executive.
   </para><para>

   Returns 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-exec-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_remove</refname>
 <refpurpose>
     Called on I2O device removal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_exec_remove </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device which was removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregisters event notification from Executive I2O device.
   </para><para>

   Returns 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-exec-lct-modified">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_lct_modified</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_lct_modified</refname>
 <refpurpose>
     Called on LCT NOTIFY reply
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_exec_lct_modified </function></funcdef>
   <paramdef>struct work_struct * <parameter>_work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>_work</parameter></term>
   <listitem>
    <para>
     work struct for a specific controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function handles asynchronus LCT NOTIFY replies. It parses the
   new LCT and if the buffer for the LCT was to small sends a LCT NOTIFY
   again, otherwise send LCT NOTIFY to get informed on next LCT change.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-exec-reply">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_reply</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_reply</refname>
 <refpurpose>
     I2O Executive reply handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_exec_reply </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u32 <parameter>m</parameter></paramdef>
   <paramdef>struct i2o_message * <parameter>msg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller from which the reply comes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     message id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     pointer to the I2O reply message
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is always called from interrupt context. If a POST WAIT
   reply was received, pass it to the complete function. If a LCT NOTIFY
   reply was received, a new event is created to handle the update.
   </para><para>

   Returns 0 on success and if the reply should not be flushed or &gt; 0
   on success and if the reply should be flushed. Returns negative error
   code on failure and if the reply should be flushed.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-exec-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_event</refname>
 <refpurpose>
     Event handling function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_exec_event </function></funcdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     Work item in occurring event
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Handles events send by the Executive device. At the moment does not do
   anything useful.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-exec-lct-notify">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_lct_notify</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_lct_notify</refname>
 <refpurpose>
     Send a asynchronus LCT NOTIFY request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_exec_lct_notify </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u32 <parameter>change_ind</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller to which the request should be send
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>change_ind</parameter></term>
   <listitem>
    <para>
     change indicator
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function sends a LCT NOTIFY request to the I2O controller with
   the change indicator change_ind. If the change_ind == 0 the controller
   replies immediately after the request. If change_ind &gt; 0 the reply is
   send after change indicator of the LCT is &gt; change_ind.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-exec-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_init</refname>
 <refpurpose>
     Registers the Exec OSM
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>i2o_exec_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>

   Registers the Exec OSM in the I2O core.
   </para><para>

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

<refentry id="API-i2o-exec-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_exec_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_exec_exit</refname>
 <refpurpose>
     Removes the Exec OSM
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_exec_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Unregisters the Exec OSM from the I2O core.
</para>
</refsect1>
</refentry>

<!-- drivers/message/i2o/bus-osm.c -->
<refentry id="API-i2o-bus-scan">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_bus_scan</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_bus_scan</refname>
 <refpurpose>
  Scan the bus for new devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_bus_scan </function></funcdef>
   <paramdef>struct i2o_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device of the bus, which should be scanned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Scans the bus dev for new / removed devices. After the scan a new LCT
   will be fetched automatically.
   </para><para>

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

<refentry id="API-i2o-bus-store-scan">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_bus_store_scan</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_bus_store_scan</refname>
 <refpurpose>
     Scan the I2O Bus Adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>i2o_bus_store_scan </function></funcdef>
   <paramdef>struct device * <parameter>d</parameter></paramdef>
   <paramdef>struct device_attribute * <parameter>attr</parameter></paramdef>
   <paramdef>const char * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>d</parameter></term>
   <listitem>
    <para>
     device which should be scanned
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     device_attribute
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     output buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     buffer size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns count.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-bus-probe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_bus_probe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_bus_probe</refname>
 <refpurpose>
     verify if dev is a I2O Bus Adapter device and install it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_bus_probe </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to verify if it is a I2O Bus Adapter device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Because we want all Bus Adapters always return 0.
   Except when we fail.  Then we are sad.
   </para><para>

   Returns 0, except when we fail to excel.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-bus-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_bus_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_bus_remove</refname>
 <refpurpose>
     remove the I2O Bus Adapter device from the system again
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_bus_remove </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O Bus Adapter device which should be removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Always returns 0.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-bus-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_bus_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_bus_init</refname>
 <refpurpose>
     Bus Adapter OSM initialization function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>i2o_bus_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>

   Only register the Bus Adapter OSM in the I2O core.
   </para><para>

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

<refentry id="API-i2o-bus-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_bus_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_bus_exit</refname>
 <refpurpose>
     Bus Adapter OSM exit function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>i2o_bus_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Unregisters Bus Adapter OSM from I2O core.
</para>
</refsect1>
</refentry>

<!-- drivers/message/i2o/device.c -->
<refentry id="API-i2o-device-claim">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_device_claim</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_device_claim</refname>
 <refpurpose>
  claim a device for use by an OSM
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_device_claim </function></funcdef>
   <paramdef>struct i2o_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device to claim
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Do the leg work to assign a device to a given OSM. If the claim succeeds,
   the owner is the primary. If the attempt fails a negative errno code
   is returned. On success zero is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-device-claim-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_device_claim_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_device_claim_release</refname>
 <refpurpose>
     release a device that the OSM is using
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_device_claim_release </function></funcdef>
   <paramdef>struct i2o_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drop a claim by an OSM on a given I2O device.
   </para><para>

   AC - some devices seem to want to refuse an unclaim until they have
   finished internal processing. It makes sense since you don't want a
   new device to go reconfiguring the entire system until you are done.
   Thus we are prepared to wait briefly.
   </para><para>

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

<!-- drivers/message/i2o/device.c -->
<refentry id="API-i2o-device-issue-claim">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_device_issue_claim</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_device_issue_claim</refname>
 <refpurpose>
  claim or release a device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_device_issue_claim </function></funcdef>
   <paramdef>struct i2o_device * <parameter>dev</parameter></paramdef>
   <paramdef>u32 <parameter>cmd</parameter></paramdef>
   <paramdef>u32 <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device to claim or release
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     claim or release command
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of claim
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Issue I2O UTIL_CLAIM or UTIL_RELEASE messages. The message to be sent
   is set by cmd. dev is the I2O device which should be claim or
   released and the type is the claim type (see the I2O spec).
   </para><para>

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

<refentry id="API-i2o-device-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_device_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_device_release</refname>
 <refpurpose>
     release the memory for a I2O device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_device_release </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device which should be released
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release the allocated memory. This function is called if refcount of
   device reaches 0 automatically.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-device-show-class-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_device_show_class_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_device_show_class_id</refname>
 <refpurpose>
     Displays class id of I2O device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>i2o_device_show_class_id </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct device_attribute * <parameter>attr</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device of which the class id should be displayed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     pointer to device attribute
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     buffer into which the class id should be printed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the number of bytes which are printed into the buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-device-show-tid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_device_show_tid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_device_show_tid</refname>
 <refpurpose>
     Displays TID of I2O device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>i2o_device_show_tid </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct device_attribute * <parameter>attr</parameter></paramdef>
   <paramdef>char * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device of which the TID should be displayed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attr</parameter></term>
   <listitem>
    <para>
     pointer to device attribute
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     buffer into which the TID should be printed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the number of bytes which are printed into the buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-device-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_device_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_device_alloc</refname>
 <refpurpose>
     Allocate a I2O device and initialize it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_device * <function>i2o_device_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>

   Allocate the memory for a I2O device and initialize locks and lists
   </para><para>

   Returns the allocated I2O device or a negative error code if the device
   could not be allocated.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-device-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_device_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_device_add</refname>
 <refpurpose>
     allocate a new I2O device and add it to the IOP
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_device_add </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>i2o_lct_entry * <parameter>entry</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller that the device is on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>entry</parameter></term>
   <listitem>
    <para>
     LCT entry of the I2O device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a new I2O device and initialize it with the LCT entry. The
   device is appended to the device list of the controller.
   </para><para>

   Returns zero on success, or a -ve errno.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-device-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_device_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_device_remove</refname>
 <refpurpose>
     remove an I2O device from the I2O core
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_device_remove </function></funcdef>
   <paramdef>struct i2o_device * <parameter>i2o_dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i2o_dev</parameter></term>
   <listitem>
    <para>
     I2O device which should be released
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Is used on I2O controller removal or LCT modification, when the device
   is removed from the system. Note that the device could still hang
   around until the refcount reaches 0.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-device-parse-lct">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_device_parse_lct</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_device_parse_lct</refname>
 <refpurpose>
     Parse a previously fetched LCT and create devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_device_parse_lct </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller from which the LCT should be parsed.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The Logical Configuration Table tells us what we can talk to on the
   board. For every entry we create an I2O device, which is registered in
   the I2O core.
   </para><para>

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

<!-- drivers/message/i2o/driver.c -->
<refentry id="API-i2o-bus-match">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_bus_match</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_bus_match</refname>
 <refpurpose>
  Tell if I2O device class id matches the class ids of the I2O driver (OSM)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_bus_match </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct device_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device which should be verified
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     the driver to match against
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Used by the bus to check if the driver wants to handle the device.
   </para><para>

   Returns 1 if the class ids of the driver match the class id of the
   device, otherwise 0.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-driver-dispatch">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_driver_dispatch</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_driver_dispatch</refname>
 <refpurpose>
     dispatch an I2O reply message
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_driver_dispatch </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u32 <parameter>m</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller of the message
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     I2O message number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The reply is delivered to the driver from which the original message
   was. This function is only called from interrupt context.
   </para><para>

   Returns 0 on success and the message should not be flushed. Returns &gt; 0
   on success and if the message should be flushed afterwords. Returns
   negative error code on failure (the message will be flushed too).
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-driver-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_driver_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_driver_init</refname>
 <refpurpose>
     initialize I2O drivers (OSMs)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>i2o_driver_init </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Registers the I2O bus and allocate memory for the array of OSMs.
   </para><para>

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

<refentry id="API-i2o-driver-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_driver_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_driver_exit</refname>
 <refpurpose>
     clean up I2O drivers (OSMs)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_driver_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Unregisters the I2O bus and frees driver array.
</para>
</refsect1>
</refentry>

<!-- drivers/message/i2o/pci.c -->
<refentry id="API-i2o-pci-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_pci_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_pci_free</refname>
 <refpurpose>
  Frees the DMA memory for the I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_pci_free </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove all allocated DMA memory and unmap memory IO regions. If MTRR
   is enabled, also remove it again.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-pci-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_pci_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_pci_alloc</refname>
 <refpurpose>
     Allocate DMA memory, map IO memory for I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_pci_alloc </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate DMA memory for a PCI (or in theory AGP) I2O controller. All
   IO mappings are also done here. If MTRR is enabled, also do add memory
   regions here.
   </para><para>

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

<refentry id="API-i2o-pci-interrupt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_pci_interrupt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_pci_interrupt</refname>
 <refpurpose>
     Interrupt handler for I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>irqreturn_t <function>i2o_pci_interrupt </function></funcdef>
   <paramdef>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>
     pointer to the I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Handle an interrupt from a PCI based I2O controller. This turns out
   to be rather simple. We keep the controller pointer in the cookie.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-pci-irq-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_pci_irq_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_pci_irq_enable</refname>
 <refpurpose>
     Allocate interrupt for I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_pci_irq_enable </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     i2o_controller that the request is for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate an interrupt for the I2O controller, and activate interrupts
   on the I2O controller.
   </para><para>

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

<refentry id="API-i2o-pci-irq-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_pci_irq_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_pci_irq_disable</refname>
 <refpurpose>
     Free interrupt for I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_pci_irq_disable </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Disable interrupts in I2O controller and then free interrupt.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-pci-probe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_pci_probe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_pci_probe</refname>
 <refpurpose>
     Probe the PCI device for an I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_pci_probe </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>const struct pci_device_id * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     PCI device to test
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     id which matched with the PCI device id table
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Probe the PCI device for any device which is a memory of the
   Intelligent, I2O class or an Adaptec Zero Channel Controller. We
   attempt to set up each such device and register it with the core.
   </para><para>

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

<refentry id="API-i2o-pci-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_pci_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_pci_remove</refname>
 <refpurpose>
     Removes a I2O controller from the system
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __devexit <function>i2o_pci_remove </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     I2O controller which should be removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reset the I2O controller, disable interrupts and remove all allocated
   resources.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-pci-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_pci_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_pci_init</refname>
 <refpurpose>
     registers I2O PCI driver in PCI subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>i2o_pci_init </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

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

<refentry id="API-i2o-pci-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_pci_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_pci_exit</refname>
 <refpurpose>
     unregisters I2O PCI driver from PCI subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>i2o_pci_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/message/i2o/i2o_block.c -->
<refentry id="API-i2o-block-device-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_device_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_device_free</refname>
 <refpurpose>
  free the memory of the I2O Block device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_block_device_free </function></funcdef>
   <paramdef>struct i2o_block_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O Block device, which should be cleaned up
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Frees the request queue, gendisk and the i2o_block_device structure.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-block-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_remove</refname>
 <refpurpose>
     remove the I2O Block device from the system again
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_remove </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O Block device which should be removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove gendisk from system and free all allocated memory.
   </para><para>

   Always returns 0.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-block-device-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_device_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_device_flush</refname>
 <refpurpose>
     Flush all dirty data of I2O device dev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_device_flush </function></funcdef>
   <paramdef>struct i2o_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device which should be flushed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Flushes all dirty data on device dev.
   </para><para>

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

<refentry id="API-i2o-block-issue-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_issue_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_issue_flush</refname>
 <refpurpose>
     device-flush interface for block-layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_issue_flush </function></funcdef>
   <paramdef>struct request_queue * <parameter>queue</parameter></paramdef>
   <paramdef>struct gendisk * <parameter>disk</parameter></paramdef>
   <paramdef>sector_t * <parameter>error_sector</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>queue</parameter></term>
   <listitem>
    <para>
     the request queue of the device which should be flushed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>disk</parameter></term>
   <listitem>
    <para>
     gendisk
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error_sector</parameter></term>
   <listitem>
    <para>
     error offset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Helper function to provide flush functionality to block-layer.
   </para><para>

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

<refentry id="API-i2o-block-device-mount">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_device_mount</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_device_mount</refname>
 <refpurpose>
     Mount (load) the media of device dev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_device_mount </function></funcdef>
   <paramdef>struct i2o_device * <parameter>dev</parameter></paramdef>
   <paramdef>u32 <parameter>media_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device which should receive the mount request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>media_id</parameter></term>
   <listitem>
    <para>
     Media Identifier
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Load a media into drive. Identifier should be set to -1, because the
   spec does not support any other value.
   </para><para>

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

<refentry id="API-i2o-block-device-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_device_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_device_lock</refname>
 <refpurpose>
     Locks the media of device dev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_device_lock </function></funcdef>
   <paramdef>struct i2o_device * <parameter>dev</parameter></paramdef>
   <paramdef>u32 <parameter>media_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device which should receive the lock request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>media_id</parameter></term>
   <listitem>
    <para>
     Media Identifier
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Lock media of device dev to prevent removal. The media identifier
   should be set to -1, because the spec does not support any other value.
   </para><para>

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

<refentry id="API-i2o-block-device-unlock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_device_unlock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_device_unlock</refname>
 <refpurpose>
     Unlocks the media of device dev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_device_unlock </function></funcdef>
   <paramdef>struct i2o_device * <parameter>dev</parameter></paramdef>
   <paramdef>u32 <parameter>media_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device which should receive the unlocked request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>media_id</parameter></term>
   <listitem>
    <para>
     Media Identifier
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unlocks the media in device dev. The media identifier should be set to
   -1, because the spec does not support any other value.
   </para><para>

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

<refentry id="API-i2o-block-device-power">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_device_power</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_device_power</refname>
 <refpurpose>
     Power management for device dev
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_device_power </function></funcdef>
   <paramdef>struct i2o_block_device * <parameter>dev</parameter></paramdef>
   <paramdef>u8 <parameter>op</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device which should receive the power management request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>op</parameter></term>
   <listitem>
    <para>
     Operation to send
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Send a power management request to the device dev.
   </para><para>

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

<refentry id="API-i2o-block-request-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_request_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_request_alloc</refname>
 <refpurpose>
     Allocate an I2O block request struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_block_request * <function>i2o_block_request_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 an I2O block request struct and initialize the list.
   </para><para>

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

<refentry id="API-i2o-block-request-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_request_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_request_free</refname>
 <refpurpose>
     Frees a I2O block request
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_block_request_free </function></funcdef>
   <paramdef>struct i2o_block_request * <parameter>ireq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ireq</parameter></term>
   <listitem>
    <para>
     I2O block request which should be freed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Frees the allocated memory (give it back to the request mempool).
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-block-sglist-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_sglist_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_sglist_alloc</refname>
 <refpurpose>
     Allocate the SG list and map it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_sglist_alloc </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>struct i2o_block_request * <parameter>ireq</parameter></paramdef>
   <paramdef>u32 ** <parameter>mptr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller to which the request belongs
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ireq</parameter></term>
   <listitem>
    <para>
     I2O block request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mptr</parameter></term>
   <listitem>
    <para>
     message body pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Builds the SG list and map it to be accessable by the controller.
   </para><para>

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

<refentry id="API-i2o-block-sglist-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_sglist_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_sglist_free</refname>
 <refpurpose>
     Frees the SG list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_block_sglist_free </function></funcdef>
   <paramdef>struct i2o_block_request * <parameter>ireq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ireq</parameter></term>
   <listitem>
    <para>
     I2O block request from which the SG should be freed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Frees the SG list from the I2O block request.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-block-prep-req-fn">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_prep_req_fn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_prep_req_fn</refname>
 <refpurpose>
     Allocates I2O block device specific struct
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_prep_req_fn </function></funcdef>
   <paramdef>struct request_queue * <parameter>q</parameter></paramdef>
   <paramdef>struct request * <parameter>req</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>q</parameter></term>
   <listitem>
    <para>
     request queue for the request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     the request to prepare
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate the necessary i2o_block_request struct and connect it to
   the request. This is needed that we not loose the SG list later on.
   </para><para>

   Returns BLKPREP_OK on success or BLKPREP_DEFER on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-block-delayed-request-fn">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_delayed_request_fn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_delayed_request_fn</refname>
 <refpurpose>
     delayed request queue function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_block_delayed_request_fn </function></funcdef>
   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     the delayed request with the queue to start
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the request queue is stopped for a disk, and there is no open
   request, a new event is created, which calls this function to start
   the queue after I2O_BLOCK_REQUEST_TIME. Otherwise the queue will never
   be started again.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-block-end-request">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_end_request</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_end_request</refname>
 <refpurpose>
     Post-processing of completed commands
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_block_end_request </function></funcdef>
   <paramdef>struct request * <parameter>req</parameter></paramdef>
   <paramdef>int <parameter>uptodate</parameter></paramdef>
   <paramdef>int <parameter>nr_bytes</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     request which should be completed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>uptodate</parameter></term>
   <listitem>
    <para>
     1 for success, 0 for I/O error, &lt; 0 for specific 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>
   Mark the request as complete. The lock must not be held when entering.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-block-reply">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_reply</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_reply</refname>
 <refpurpose>
     Block OSM reply handler.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_reply </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u32 <parameter>m</parameter></paramdef>
   <paramdef>struct i2o_message * <parameter>msg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller from which the message arrives
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     message id of reply
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     the actual I2O message reply
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function gets all the message replies.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-block-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_open</refname>
 <refpurpose>
     Open the block device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_open </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     inode for block device being opened
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     file to open
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Power up the device, mount and lock the media. This function is called,
   if the block device is opened for access.
   </para><para>

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

<refentry id="API-i2o-block-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_release</refname>
 <refpurpose>
     Release the I2O block device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_release </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     inode for block device being released
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     file to close
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unlock and unmount the media, and power down the device. Gets called if
   the block device is closed.
   </para><para>

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

<refentry id="API-i2o-block-ioctl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_ioctl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_ioctl</refname>
 <refpurpose>
     Issue device specific ioctl calls.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_ioctl </function></funcdef>
   <paramdef>struct inode * <parameter>inode</parameter></paramdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
   <paramdef>unsigned int <parameter>cmd</parameter></paramdef>
   <paramdef>unsigned long <parameter>arg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>inode</parameter></term>
   <listitem>
    <para>
     inode for block device ioctl
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     file for ioctl
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     ioctl command
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>arg</parameter></term>
   <listitem>
    <para>
     arg
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Handles ioctl request for the block device.
   </para><para>

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

<refentry id="API-i2o-block-media-changed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_media_changed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_media_changed</refname>
 <refpurpose>
     Have we seen a media change?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_media_changed </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>
     gendisk which should be verified
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Verifies if the media has changed.
   </para><para>

   Returns 1 if the media was changed or 0 otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-block-transfer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_transfer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_transfer</refname>
 <refpurpose>
     Transfer a request to/from the I2O controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_transfer </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 which should be transfered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function converts the request into a I2O message. The necessary
   DMA buffers are allocated and after everything is setup post the message
   to the I2O controller. No cleanup is done by this function. It is done
   on the interrupt side when the reply arrives.
   </para><para>

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

<refentry id="API-i2o-block-request-fn">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_request_fn</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_request_fn</refname>
 <refpurpose>
     request queue handling function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_block_request_fn </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 from which the request could be fetched
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Takes the next request from the queue, transfers it and if no error
   occurs dequeue it from the queue. On arrival of the reply the message
   will be processed further. If an error occurs requeue the request.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-block-device-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_device_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_device_alloc</refname>
 <refpurpose>
     Allocate memory for a I2O Block device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_block_device * <function>i2o_block_device_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>

   Allocate memory for the i2o_block_device struct, gendisk and request
   queue and initialize them as far as no additional information is needed.
   </para><para>

   Returns a pointer to the allocated I2O Block device on succes or a
   negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-block-probe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_probe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_probe</refname>
 <refpurpose>
     verify if dev is a I2O Block device and install it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_block_probe </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to verify if it is a I2O Block device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   We only verify if the user_tid of the device is 0xfff and then install
   the device. Otherwise it is used by some other device (e. g. RAID).
   </para><para>

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

<refentry id="API-i2o-block-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_init</refname>
 <refpurpose>
     Block OSM initialization function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>i2o_block_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>

   Allocate the slab and mempool for request structs, registers i2o_block
   block device and finally register the Block OSM in the I2O core.
   </para><para>

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

<refentry id="API-i2o-block-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_block_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_block_exit</refname>
 <refpurpose>
     Block OSM exit function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>i2o_block_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Unregisters Block OSM from I2O core, unregisters i2o_block block device
   and frees the mempool and slab.
</para>
</refsect1>
</refentry>

<!-- drivers/message/i2o/i2o_scsi.c -->
<refentry id="API-i2o-scsi-get-host">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_get_host</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_get_host</refname>
 <refpurpose>
  Get an I2O SCSI host
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2o_scsi_host * <function>i2o_scsi_get_host </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller to for which to get the SCSI host
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If the I2O controller already exists as SCSI host, the SCSI host
   is returned, otherwise the I2O controller is added to the SCSI
   core.
   </para><para>

   Returns pointer to the I2O SCSI host on success or NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-scsi-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_remove</refname>
 <refpurpose>
     Remove I2O device from SCSI core
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_scsi_remove </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device which should be removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes the I2O device from the SCSI core again.
   </para><para>

   Returns 0 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-scsi-probe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_probe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_probe</refname>
 <refpurpose>
     verify if dev is a I2O SCSI device and install it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_scsi_probe </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to verify if it is a I2O SCSI device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Retrieve channel, id and lun for I2O device. If everthing goes well
   register the I2O device as SCSI device on the I2O SCSI controller.
   </para><para>

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

<refentry id="API-i2o-scsi-reply">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_reply</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_reply</refname>
 <refpurpose>
     SCSI OSM message reply handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_scsi_reply </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
   <paramdef>u32 <parameter>m</parameter></paramdef>
   <paramdef>struct i2o_message * <parameter>msg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     controller issuing the reply
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     message id for flushing
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     the message from the controller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Process reply messages (interrupts in normal scsi controller think).
   We can get a variety of messages to process. The normal path is
   scsi command completions. We must also deal with IOP failures,
   the reply to a bus reset and the reply to a LUN query.
   </para><para>

   Returns 0 on success and if the reply should not be flushed or &gt; 0
   on success and if the reply should be flushed. Returns negative error
   code on failure and if the reply should be flushed.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-scsi-notify-device-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_notify_device_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_notify_device_add</refname>
 <refpurpose>
     Retrieve notifications of added devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_scsi_notify_device_add </function></funcdef>
   <paramdef>struct i2o_device * <parameter>i2o_dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i2o_dev</parameter></term>
   <listitem>
    <para>
     the I2O device which was added
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a I2O device is added we catch the notification, because I2O classes
   other then SCSI peripheral will not be received through
   <function>i2o_scsi_probe</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-scsi-notify-device-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_notify_device_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_notify_device_remove</refname>
 <refpurpose>
     Retrieve notifications of removed devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_scsi_notify_device_remove </function></funcdef>
   <paramdef>struct i2o_device * <parameter>i2o_dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i2o_dev</parameter></term>
   <listitem>
    <para>
     the I2O device which was removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a I2O device is removed, we catch the notification to remove the
   corresponding SCSI device.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-scsi-notify-controller-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_notify_controller_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_notify_controller_add</refname>
 <refpurpose>
     Retrieve notifications of added controllers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_scsi_notify_controller_add </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     the controller which was added
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a I2O controller is added, we catch the notification to add a
   corresponding Scsi_Host.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-scsi-notify-controller-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_notify_controller_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_notify_controller_remove</refname>
 <refpurpose>
     Retrieve notifications of removed controllers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_scsi_notify_controller_remove </function></funcdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     the controller which was removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a I2O controller is removed, we catch the notification to remove the
   corresponding Scsi_Host.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-scsi-queuecommand">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_queuecommand</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_queuecommand</refname>
 <refpurpose>
     queue a SCSI command
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_scsi_queuecommand </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
   <paramdef>void (*<parameter>done</parameter>)
     <funcparams>struct scsi_cmnd *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     scsi command pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>done</parameter></term>
   <listitem>
    <para>
     callback for completion
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Issue a scsi command asynchronously. Return 0 on success or 1 if
   we hit an error (normally message queue congestion). The only
   minor complication here is that I2O deals with the device addressing
   so we have to map the bus/dev/lun back to an I2O handle as well
   as faking absent devices ourself.
</para>
</refsect1>
<refsect1>
<title>Locks</title>
<para>
   takes the controller lock on error path only
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-scsi-abort">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_abort</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_abort</refname>
 <refpurpose>
     abort a running command
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_scsi_abort </function></funcdef>
   <paramdef>struct scsi_cmnd * <parameter>SCpnt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>SCpnt</parameter></term>
   <listitem>
    <para>
     command to abort
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Ask the I2O controller to abort a command. This is an asynchrnous
   process and our callback handler will see the command complete with an
   aborted message if it succeeds.
   </para><para>

   Returns 0 if the command is successfully aborted or negative error code
   on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-scsi-bios-param">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_bios_param</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_bios_param</refname>
 <refpurpose>
     Invent disk geometry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_scsi_bios_param </function></funcdef>
   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
   <paramdef>struct block_device * <parameter>dev</parameter></paramdef>
   <paramdef>sector_t <parameter>capacity</parameter></paramdef>
   <paramdef>int * <parameter>ip</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sdev</parameter></term>
   <listitem>
    <para>
     scsi device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     block layer device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>capacity</parameter></term>
   <listitem>
    <para>
     size in sectors
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ip</parameter></term>
   <listitem>
    <para>
     geometry array
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is anyone's guess quite frankly. We use the same rules everyone
   else appears to and hope. It seems to work.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-scsi-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_init</refname>
 <refpurpose>
     SCSI OSM initialization function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>i2o_scsi_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>

   Register SCSI OSM into I2O core.
   </para><para>

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

<refentry id="API-i2o-scsi-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_scsi_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_scsi_exit</refname>
 <refpurpose>
     SCSI OSM exit function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>i2o_scsi_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Unregisters SCSI OSM from I2O core.
</para>
</refsect1>
</refentry>

<!-- drivers/message/i2o/i2o_proc.c -->
<refentry id="API-i2o-get-class-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_get_class_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_get_class_name</refname>
 <refpurpose>
  do i2o class name lookup
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>i2o_get_class_name </function></funcdef>
   <paramdef>int <parameter>class</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>class</parameter></term>
   <listitem>
    <para>
     class number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return a descriptive string for an i2o class.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-proc-create-entries">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_proc_create_entries</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_proc_create_entries</refname>
 <refpurpose>
     Creates proc dir entries
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_proc_create_entries </function></funcdef>
   <paramdef>struct proc_dir_entry * <parameter>dir</parameter></paramdef>
   <paramdef>i2o_proc_entry * <parameter>i2o_pe</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dir</parameter></term>
   <listitem>
    <para>
     proc dir entry under which the entries should be placed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>i2o_pe</parameter></term>
   <listitem>
    <para>
     pointer to the entries which should be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     pointer to I2O controller or device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Create proc dir entries for a I2O controller or I2O device.
   </para><para>

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

<refentry id="API-i2o-proc-subdir-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_proc_subdir_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_proc_subdir_remove</refname>
 <refpurpose>
     Remove child entries from a proc entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_proc_subdir_remove </function></funcdef>
   <paramdef>struct proc_dir_entry * <parameter>dir</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dir</parameter></term>
   <listitem>
    <para>
     proc dir entry from which the childs should be removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over each i2o proc entry under dir and remove it. If the child
   also has entries, remove them too.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-proc-device-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_proc_device_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_proc_device_add</refname>
 <refpurpose>
     Add an I2O device to the proc dir
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_proc_device_add </function></funcdef>
   <paramdef>struct proc_dir_entry * <parameter>dir</parameter></paramdef>
   <paramdef>struct i2o_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dir</parameter></term>
   <listitem>
    <para>
     proc dir entry to which the device should be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     I2O device which should be added
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add an I2O device to the proc dir entry dir and create the entries for
   the device depending on the class of the I2O device.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-proc-iop-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_proc_iop_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_proc_iop_add</refname>
 <refpurpose>
     Add an I2O controller to the i2o proc tree
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2o_proc_iop_add </function></funcdef>
   <paramdef>struct proc_dir_entry * <parameter>dir</parameter></paramdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dir</parameter></term>
   <listitem>
    <para>
     parent proc dir entry
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller which should be added
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add the entries to the parent proc dir entry. Also each device is added
   to the controllers proc dir entry.
   </para><para>

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

<refentry id="API-i2o-proc-iop-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_proc_iop_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_proc_iop_remove</refname>
 <refpurpose>
     Removes an I2O controller from the i2o proc tree
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2o_proc_iop_remove </function></funcdef>
   <paramdef>struct proc_dir_entry * <parameter>dir</parameter></paramdef>
   <paramdef>struct i2o_controller * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dir</parameter></term>
   <listitem>
    <para>
     parent proc dir entry
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     I2O controller which should be removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over each i2o proc entry and search controller c. If it is found
   remove it from the tree.
</para>
</refsect1>
</refentry>

<refentry id="API-i2o-proc-fs-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_proc_fs_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_proc_fs_create</refname>
 <refpurpose>
     Create the i2o proc fs.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>i2o_proc_fs_create </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Iterate over each I2O controller and create the entries for it.
   </para><para>

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

<refentry id="API-i2o-proc-fs-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_proc_fs_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_proc_fs_destroy</refname>
 <refpurpose>
     Cleanup the all i2o proc entries
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __exit <function>i2o_proc_fs_destroy </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Iterate over each I2O controller and remove the entries for it.
   </para><para>

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

<refentry id="API-i2o-proc-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_proc_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_proc_init</refname>
 <refpurpose>
     Init function for procfs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>i2o_proc_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>

   Registers Proc OSM and creates procfs entries.
   </para><para>

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

<refentry id="API-i2o-proc-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2o_proc_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2o_proc_exit</refname>
 <refpurpose>
     Exit function for procfs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void __exit <function>i2o_proc_exit </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Unregisters Proc OSM and removes procfs entries.
</para>
</refsect1>
</refentry>

     </sect1>
  </chapter>

  <chapter id="snddev">
     <title>Sound Devices</title>
<!-- include/sound/core.h -->
<refentry id="API-snd-register-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_register_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_register_device</refname>
 <refpurpose>
  Register the ALSA device file for the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_register_device </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>int <parameter>dev</parameter></paramdef>
   <paramdef>const struct file_operations * <parameter>f_ops</parameter></paramdef>
   <paramdef>void * <parameter>private_data</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the device type, SNDRV_DEVICE_TYPE_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the device index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>f_ops</parameter></term>
   <listitem>
    <para>
     the file operations
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>private_data</parameter></term>
   <listitem>
    <para>
     user pointer for f_ops-&gt;<function>open</function>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the device file name
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers an ALSA device file for the given card.
   The operators have to be set in reg parameter.
   </para><para>

   This function uses the card's device pointer to link to the
   correct &amp;struct device.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-printk">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_printk</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_printk</refname>
 <refpurpose>
     printk wrapper
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_printk </function></funcdef>
   <paramdef> <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>args...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Works like <function>print</function> but prints the file and the line of the caller
   when configured with CONFIG_SND_VERBOSE_PRINTK.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-printd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_printd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_printd</refname>
 <refpurpose>
     debug printk
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_printd </function></funcdef>
   <paramdef> <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>args...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Compiled only when Works like <function>snd_printk</function> for debugging purpose.
   Ignored when CONFIG_SND_DEBUG is not set.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-assert">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_assert</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_assert</refname>
 <refpurpose>
     run-time assertion macro
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_assert </function></funcdef>
   <paramdef> <parameter>expr</parameter></paramdef>
   <paramdef> <parameter>args...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>expr</parameter></term>
   <listitem>
    <para>
     expression
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro checks the expression in run-time and invokes the commands
   given in the rest arguments if the assertion is failed.
   When CONFIG_SND_DEBUG is not set, the expression is executed but
   not checked.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-printdd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_printdd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_printdd</refname>
 <refpurpose>
     debug printk
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>snd_printdd </function></funcdef>
   <paramdef> <parameter>format</parameter></paramdef>
   <paramdef> <parameter>args...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     format string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Compiled only when Works like <function>snd_printk</function> for debugging purpose.
   Ignored when CONFIG_SND_DEBUG_DETECT is not set.
</para>
</refsect1>
</refentry>

<!-- sound/sound_core.c -->
<refentry id="API-register-sound-special-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_sound_special_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_sound_special_device</refname>
 <refpurpose>
  register a special sound node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_sound_special_device </function></funcdef>
   <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
   <paramdef>int <parameter>unit</parameter></paramdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fops</parameter></term>
   <listitem>
    <para>
     File operations for the driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>unit</parameter></term>
   <listitem>
    <para>
     Unit number to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a special sound device by minor number from the sound
   subsystem. The allocated number is returned on succes. On failure
   a negative error code is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-register-sound-mixer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_sound_mixer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_sound_mixer</refname>
 <refpurpose>
     register a mixer device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_sound_mixer </function></funcdef>
   <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
   <paramdef>int <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fops</parameter></term>
   <listitem>
    <para>
     File operations for the driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a mixer device. Unit is the number of the mixer requested.
   Pass -1 to request the next free mixer unit. On success the allocated
   number is returned, on failure a negative error code is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-register-sound-midi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_sound_midi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_sound_midi</refname>
 <refpurpose>
     register a midi device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_sound_midi </function></funcdef>
   <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
   <paramdef>int <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fops</parameter></term>
   <listitem>
    <para>
     File operations for the driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a midi device. Unit is the number of the midi device requested.
   Pass -1 to request the next free midi unit. On success the allocated
   number is returned, on failure a negative error code is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-register-sound-dsp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_sound_dsp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_sound_dsp</refname>
 <refpurpose>
     register a DSP device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_sound_dsp </function></funcdef>
   <paramdef>const struct file_operations * <parameter>fops</parameter></paramdef>
   <paramdef>int <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fops</parameter></term>
   <listitem>
    <para>
     File operations for the driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a DSP device. Unit is the number of the DSP requested.
   Pass -1 to request the next free DSP unit. On success the allocated
   number is returned, on failure a negative error code is returned.
   </para><para>

   This function allocates both the audio and dsp device entries together
   and will always allocate them as a matching pair - eg dsp3/audio3
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-sound-special">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_sound_special</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_sound_special</refname>
 <refpurpose>
     unregister a special sound device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_sound_special </function></funcdef>
   <paramdef>int <parameter>unit</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>unit</parameter></term>
   <listitem>
    <para>
     unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release a sound device that was allocated with
   <function>register_sound_special</function>. The unit passed is the return value from
   the register function.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-sound-mixer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_sound_mixer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_sound_mixer</refname>
 <refpurpose>
     unregister a mixer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_sound_mixer </function></funcdef>
   <paramdef>int <parameter>unit</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>unit</parameter></term>
   <listitem>
    <para>
     unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release a sound device that was allocated with <function>register_sound_mixer</function>.
   The unit passed is the return value from the register function.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-sound-midi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_sound_midi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_sound_midi</refname>
 <refpurpose>
     unregister a midi device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_sound_midi </function></funcdef>
   <paramdef>int <parameter>unit</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>unit</parameter></term>
   <listitem>
    <para>
     unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release a sound device that was allocated with <function>register_sound_midi</function>.
   The unit passed is the return value from the register function.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-sound-dsp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_sound_dsp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_sound_dsp</refname>
 <refpurpose>
     unregister a DSP device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>unregister_sound_dsp </function></funcdef>
   <paramdef>int <parameter>unit</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>unit</parameter></term>
   <listitem>
    <para>
     unit number to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release a sound device that was allocated with <function>register_sound_dsp</function>.
   The unit passed is the return value from the register function.
   </para><para>

   Both of the allocated units are released together automatically.
</para>
</refsect1>
</refentry>

<!-- include/sound/pcm.h -->
<refentry id="API-snd-pcm-playback-ready">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_playback_ready</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_playback_ready</refname>
 <refpurpose>
  check whether the playback buffer is available
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_playback_ready </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether enough free space is available on the playback buffer.
   </para><para>

   Returns non-zero if available, or zero if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-capture-ready">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_capture_ready</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_capture_ready</refname>
 <refpurpose>
     check whether the capture buffer is available
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_capture_ready </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether enough capture data is available on the capture buffer.
   </para><para>

   Returns non-zero if available, or zero if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-playback-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_playback_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_playback_data</refname>
 <refpurpose>
     check whether any data exists on the playback buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_playback_data </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether any data exists on the playback buffer. If stop_threshold
   is bigger or equal to boundary, then this function returns always non-zero.
   </para><para>

   Returns non-zero if exists, or zero if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-playback-empty">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_playback_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_playback_empty</refname>
 <refpurpose>
     check whether the playback buffer is empty
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_playback_empty </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether the playback buffer is empty.
   </para><para>

   Returns non-zero if empty, or zero if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-capture-empty">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_capture_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_capture_empty</refname>
 <refpurpose>
     check whether the capture buffer is empty
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_capture_empty </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether the capture buffer is empty.
   </para><para>

   Returns non-zero if empty, or zero if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-format-cpu-endian">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_format_cpu_endian</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_format_cpu_endian</refname>
 <refpurpose>
     Check the PCM format is CPU-endian
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_format_cpu_endian </function></funcdef>
   <paramdef>snd_pcm_format_t <parameter>format</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     the format to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 1 if the given PCM format is CPU-endian, 0 if
   opposite, or a negative error code if endian not specified.
</para>
</refsect1>
</refentry>

<!-- sound/core/pcm.c -->
<refentry id="API-snd-pcm-new-stream">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_new_stream</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_new_stream</refname>
 <refpurpose>
  create a new PCM stream
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_new_stream </function></funcdef>
   <paramdef>struct snd_pcm * <parameter>pcm</parameter></paramdef>
   <paramdef>int <parameter>stream</parameter></paramdef>
   <paramdef>int <parameter>substream_count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     the pcm instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>stream</parameter></term>
   <listitem>
    <para>
     the stream direction, SNDRV_PCM_STREAM_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>substream_count</parameter></term>
   <listitem>
    <para>
     the number of substreams
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new stream for the pcm.
   The corresponding stream on the pcm must have been empty before
   calling this, i.e. zero must be given to the argument of
   <function>snd_pcm_new</function>.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_new</refname>
 <refpurpose>
     create a new PCM instance
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_new </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>char * <parameter>id</parameter></paramdef>
   <paramdef>int <parameter>device</parameter></paramdef>
   <paramdef>int <parameter>playback_count</parameter></paramdef>
   <paramdef>int <parameter>capture_count</parameter></paramdef>
   <paramdef>struct snd_pcm ** <parameter>rpcm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the id string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device index (zero based)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>playback_count</parameter></term>
   <listitem>
    <para>
     the number of substreams for playback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>capture_count</parameter></term>
   <listitem>
    <para>
     the number of substreams for capture
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rpcm</parameter></term>
   <listitem>
    <para>
     the pointer to store the new pcm instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new PCM instance.
   </para><para>

   The pcm operators have to be set afterwards to the new instance
   via <function>snd_pcm_set_ops</function>.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<!-- sound/core/device.c -->
<refentry id="API-snd-device-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_device_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_device_new</refname>
 <refpurpose>
  create an ALSA device component
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_device_new </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>snd_device_type_t <parameter>type</parameter></paramdef>
   <paramdef>void * <parameter>device_data</parameter></paramdef>
   <paramdef>struct snd_device_ops * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the device type, SNDRV_DEV_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device_data</parameter></term>
   <listitem>
    <para>
     the data pointer of this device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     the operator table
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new device component for the given data pointer.
   The device will be assigned to the card and managed together
   by the card.
   </para><para>

   The data pointer plays a role as the identifier, too, so the
   pointer address must be unique and unchanged.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-device-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_device_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_device_free</refname>
 <refpurpose>
     release the device from the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_device_free </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>void * <parameter>device_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device_data</parameter></term>
   <listitem>
    <para>
     the data pointer to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes the device from the list on the card and invokes the
   callbacks, dev_disconnect and dev_free, corresponding to the state.
   Then release the device.
   </para><para>

   Returns zero if successful, or a negative error code on failure or if the
   device not found.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-device-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_device_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_device_register</refname>
 <refpurpose>
     register the device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_device_register </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>void * <parameter>device_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device_data</parameter></term>
   <listitem>
    <para>
     the data pointer to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers the device which was already created via
   <function>snd_device_new</function>.  Usually this is called from <function>snd_card_register</function>,
   but it can be called later if any new devices are created after
   invocation of <function>snd_card_register</function>.
   </para><para>

   Returns zero if successful, or a negative error code on failure or if the
   device not found.
</para>
</refsect1>
</refentry>

<!-- sound/core/info.c -->
<refentry id="API-snd-iprintf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_iprintf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_iprintf</refname>
 <refpurpose>
  printf on the procfs buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_iprintf </function></funcdef>
   <paramdef>struct snd_info_buffer * <parameter>buffer</parameter></paramdef>
   <paramdef>char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     the procfs buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     the printf format
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Outputs the string on the procfs buffer just like <function>printf</function>.
   </para><para>

   Returns the size of output string.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-info-get-line">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_get_line</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_get_line</refname>
 <refpurpose>
     read one line from the procfs buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_info_get_line </function></funcdef>
   <paramdef>struct snd_info_buffer * <parameter>buffer</parameter></paramdef>
   <paramdef>char * <parameter>line</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     the procfs buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>line</parameter></term>
   <listitem>
    <para>
     the buffer to store
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     the max. buffer size - 1
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reads one line from the buffer and stores the string.
   </para><para>

   Returns zero if successful, or 1 if error or EOF.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-info-get-str">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_get_str</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_get_str</refname>
 <refpurpose>
     parse a string token
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>char * <function>snd_info_get_str </function></funcdef>
   <paramdef>char * <parameter>dest</parameter></paramdef>
   <paramdef>char * <parameter>src</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dest</parameter></term>
   <listitem>
    <para>
     the buffer to store the string token
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     the original string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     the max. length of token - 1
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Parses the original string and copy a token to the given
   string buffer.
   </para><para>

   Returns the updated pointer of the original string so that
   it can be used for the next call.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-info-create-module-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_create_module_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_create_module_entry</refname>
 <refpurpose>
     create an info entry for the given module
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_info_entry * <function>snd_info_create_module_entry </function></funcdef>
   <paramdef>struct module * <parameter>module</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct snd_info_entry * <parameter>parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>module</parameter></term>
   <listitem>
    <para>
     the module pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the file name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     the parent directory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new info entry and assigns it to the given module.
   </para><para>

   Returns the pointer of the new instance, or NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-info-create-card-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_create_card_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_create_card_entry</refname>
 <refpurpose>
     create an info entry for the given card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_info_entry * <function>snd_info_create_card_entry </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct snd_info_entry * <parameter>parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the file name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     the parent directory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new info entry and assigns it to the given card.
   </para><para>

   Returns the pointer of the new instance, or NULL on failure.
</para>
</refsect1>
</refentry>

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

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

   For releasing this entry, use <function>snd_device_free</function> instead of
   <function>snd_info_free_entry</function>. 
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-info-free-entry">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_free_entry</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_free_entry</refname>
 <refpurpose>
     release the info entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_info_free_entry </function></funcdef>
   <paramdef>struct snd_info_entry * <parameter>entry</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>entry</parameter></term>
   <listitem>
    <para>
     the info entry
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases the info entry.  Don't call this after registered.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-info-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_info_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_info_register</refname>
 <refpurpose>
     register the info entry
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_info_register </function></funcdef>
   <paramdef>struct snd_info_entry * <parameter>entry</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>entry</parameter></term>
   <listitem>
    <para>
     the info entry
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers the proc info entry.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<!-- sound/core/rawmidi.c -->
<refentry id="API-snd-rawmidi-receive">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_receive</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_receive</refname>
 <refpurpose>
  receive the input data from the device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_receive </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
   <paramdef>const unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     the buffer pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the data size to read
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reads the data from the internal buffer.
   </para><para>

   Returns the size of read data, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-transmit-empty">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_transmit_empty</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_transmit_empty</refname>
 <refpurpose>
     check whether the output buffer is empty
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_transmit_empty </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 1 if the internal output buffer is empty, 0 if not.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-transmit-peek">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_transmit_peek</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_transmit_peek</refname>
 <refpurpose>
     copy data from the internal buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_transmit_peek </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     the buffer pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     data size to transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies data from the internal output buffer to the given buffer.
   </para><para>

   Call this in the interrupt handler when the midi output is ready,
   and call <function>snd_rawmidi_transmit_ack</function> after the transmission is
   finished.
   </para><para>

   Returns the size of copied data, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-transmit-ack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_transmit_ack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_transmit_ack</refname>
 <refpurpose>
     acknowledge the transmission
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_transmit_ack </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the tranferred count
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Advances the hardware pointer for the internal output buffer with
   the given size and updates the condition.
   Call after the transmission is finished.
   </para><para>

   Returns the advanced size if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-transmit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_transmit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_transmit</refname>
 <refpurpose>
     copy from the buffer to the device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_transmit </function></funcdef>
   <paramdef>struct snd_rawmidi_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
   <paramdef>int <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the rawmidi substream
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     the buffer pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the data size to transfer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies data from the buffer to the device and advances the pointer.
   </para><para>

   Returns the copied size if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_new</refname>
 <refpurpose>
     create a rawmidi instance
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_rawmidi_new </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>char * <parameter>id</parameter></paramdef>
   <paramdef>int <parameter>device</parameter></paramdef>
   <paramdef>int <parameter>output_count</parameter></paramdef>
   <paramdef>int <parameter>input_count</parameter></paramdef>
   <paramdef>struct snd_rawmidi ** <parameter>rrawmidi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the id string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>output_count</parameter></term>
   <listitem>
    <para>
     the number of output streams
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>input_count</parameter></term>
   <listitem>
    <para>
     the number of input streams
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rrawmidi</parameter></term>
   <listitem>
    <para>
     the pointer to store the new rawmidi instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new rawmidi instance.
   Use <function>snd_rawmidi_set_ops</function> to set the operators to the new instance.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-rawmidi-set-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_rawmidi_set_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_rawmidi_set_ops</refname>
 <refpurpose>
     set the rawmidi operators
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_rawmidi_set_ops </function></funcdef>
   <paramdef>struct snd_rawmidi * <parameter>rmidi</parameter></paramdef>
   <paramdef>int <parameter>stream</parameter></paramdef>
   <paramdef>struct snd_rawmidi_ops * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rmidi</parameter></term>
   <listitem>
    <para>
     the rawmidi instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>stream</parameter></term>
   <listitem>
    <para>
     the stream direction, SNDRV_RAWMIDI_STREAM_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     the operator table
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets the rawmidi operators for the given stream direction.
</para>
</refsect1>
</refentry>

<!-- sound/core/sound.c -->
<refentry id="API-snd-request-card">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_request_card</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_request_card</refname>
 <refpurpose>
  try to load the card module
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_request_card </function></funcdef>
   <paramdef>int <parameter>card</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Tries to load the module <quote>snd-card-X</quote> for the given card number
   via KMOD.  Returns immediately if already loaded.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-lookup-minor-data">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_lookup_minor_data</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_lookup_minor_data</refname>
 <refpurpose>
     get user data of a registered device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>snd_lookup_minor_data </function></funcdef>
   <paramdef>unsigned int <parameter>minor</parameter></paramdef>
   <paramdef>int <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>minor</parameter></term>
   <listitem>
    <para>
     the minor number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     device type (SNDRV_DEVICE_TYPE_XXX)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks that a minor device with the specified type is registered, and returns
   its user data pointer.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-register-device-for-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_register_device_for_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_register_device_for_dev</refname>
 <refpurpose>
     Register the ALSA device file for the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_register_device_for_dev </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>int <parameter>dev</parameter></paramdef>
   <paramdef>const struct file_operations * <parameter>f_ops</parameter></paramdef>
   <paramdef>void * <parameter>private_data</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>struct device * <parameter>device</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the device type, SNDRV_DEVICE_TYPE_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the device index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>f_ops</parameter></term>
   <listitem>
    <para>
     the file operations
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>private_data</parameter></term>
   <listitem>
    <para>
     user pointer for f_ops-&gt;<function>open</function>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     the device file name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the &amp;struct device to link this new device to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers an ALSA device file for the given card.
   The operators have to be set in reg parameter.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-unregister-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_unregister_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_unregister_device</refname>
 <refpurpose>
     unregister the device on the given card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_unregister_device </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>int <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the device type, SNDRV_DEVICE_TYPE_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the device index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregisters the device file already registered via
   <function>snd_register_device</function>.
   </para><para>

   Returns zero if sucecessful, or a negative error code on failure
</para>
</refsect1>
</refentry>

<!-- sound/core/memory.c -->
<refentry id="API-copy-to-user-fromio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>copy_to_user_fromio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>copy_to_user_fromio</refname>
 <refpurpose>
  copy data from mmio-space to user-space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>copy_to_user_fromio </function></funcdef>
   <paramdef>void __user * <parameter>dst</parameter></paramdef>
   <paramdef>const volatile void __iomem * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     the destination pointer on user-space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     the source pointer on mmio
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the data size to copy in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies the data from mmio-space to user-space.
   </para><para>

   Returns zero if successful, or non-zero on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-copy-from-user-toio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>copy_from_user_toio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>copy_from_user_toio</refname>
 <refpurpose>
     copy data from user-space to mmio-space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>copy_from_user_toio </function></funcdef>
   <paramdef>volatile void __iomem * <parameter>dst</parameter></paramdef>
   <paramdef>const void __user * <parameter>src</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     the destination pointer on mmio-space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     the source pointer on user-space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the data size to copy in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies the data from user-space to mmio-space.
   </para><para>

   Returns zero if successful, or non-zero on failure.
</para>
</refsect1>
</refentry>

<!-- sound/core/pcm_memory.c -->
<refentry id="API-snd-pcm-lib-preallocate-free-for-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_preallocate_free_for_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_preallocate_free_for_all</refname>
 <refpurpose>
  release all pre-allocated buffers on the pcm
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_preallocate_free_for_all </function></funcdef>
   <paramdef>struct snd_pcm * <parameter>pcm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     the pcm instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases all the pre-allocated buffers on the given pcm.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-preallocate-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_preallocate_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_preallocate_pages</refname>
 <refpurpose>
     pre-allocation for the given DMA type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_preallocate_pages </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>struct device * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>size_t <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     DMA type (SNDRV_DMA_TYPE_*)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     DMA type dependant data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the requested pre-allocation size in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     the max. allowed pre-allocation size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Do pre-allocation for the given DMA buffer type.
   </para><para>

   When substream-&gt;dma_buf_id is set, the function tries to look for
   the reserved buffer, and the buffer is not freed but reserved at
   destruction time.  The dma_buf_id must be unique for all systems
   (in the same DMA buffer type) e.g. using <function>snd_dma_pci_buf_id</function>.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-preallocate-pages-for-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_preallocate_pages_for_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_preallocate_pages_for_all</refname>
 <refpurpose>
     pre-allocation for continous memory type (all substreams)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_preallocate_pages_for_all </function></funcdef>
   <paramdef>struct snd_pcm * <parameter>pcm</parameter></paramdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>size_t <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     the pcm instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     DMA type (SNDRV_DMA_TYPE_*)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     DMA type dependant data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the requested pre-allocation size in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     the max. allowed pre-allocation size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Do pre-allocation to all substreams of the given pcm for the
   specified DMA type.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-sgbuf-ops-page">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_sgbuf_ops_page</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_sgbuf_ops_page</refname>
 <refpurpose>
     get the page struct at the given offset
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page * <function>snd_pcm_sgbuf_ops_page </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned long <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     the buffer offset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the page struct at the given buffer offset.
   Used as the page callback of PCM ops.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-malloc-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_malloc_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_malloc_pages</refname>
 <refpurpose>
     allocate the DMA buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_malloc_pages </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the substream to allocate the DMA buffer to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the requested buffer size in bytes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates the DMA buffer on the BUS type given earlier to
   <function>snd_pcm_lib_preallocate_xxx_pages</function>.
   </para><para>

   Returns 1 if the buffer is changed, 0 if not changed, or a negative
   code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-free-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_free_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_free_pages</refname>
 <refpurpose>
     release the allocated DMA buffer.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_free_pages </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the substream to release the DMA buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases the DMA buffer allocated via <function>snd_pcm_lib_malloc_pages</function>.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<!-- sound/core/init.c -->
<refentry id="API-snd-card-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_new</refname>
 <refpurpose>
  create and initialize a soundcard structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_card * <function>snd_card_new </function></funcdef>
   <paramdef>int <parameter>idx</parameter></paramdef>
   <paramdef>const char * <parameter>xid</parameter></paramdef>
   <paramdef>struct module * <parameter>module</parameter></paramdef>
   <paramdef>int <parameter>extra_size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>idx</parameter></term>
   <listitem>
    <para>
     card index (address) [0 ... (SNDRV_CARDS-1)]
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>xid</parameter></term>
   <listitem>
    <para>
     card identification (ASCII string)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>module</parameter></term>
   <listitem>
    <para>
     top level module for locking
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>extra_size</parameter></term>
   <listitem>
    <para>
     allocate this extra size after the main soundcard structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates and initializes a soundcard structure.
   </para><para>

   Returns kmallocated snd_card structure. Creates the ALSA control interface
   (which is blocked until snd_card_register function is called).
</para>
</refsect1>
</refentry>

<refentry id="API-snd-card-disconnect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_disconnect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_disconnect</refname>
 <refpurpose>
     disconnect all APIs from the file-operations (user space)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_disconnect </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Disconnects all APIs from the file-operations (user space).
   </para><para>

   Returns zero, otherwise a negative error code.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   The current implementation replaces all active file-&gt;f_op with special
   dummy file operations (they do nothing except release).
</para>
</refsect1>
</refentry>

<refentry id="API-snd-card-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_register</refname>
 <refpurpose>
     register the soundcard
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_register </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function registers all the devices assigned to the soundcard.
   Until calling this, the ALSA control interface is blocked from the
   external accesses.  Thus, you should call this function at the end
   of the initialization of the card.
   </para><para>

   Returns zero otherwise a negative error code if the registrain failed.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-component-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_component_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_component_add</refname>
 <refpurpose>
     add a component string
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_component_add </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>const char * <parameter>component</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>component</parameter></term>
   <listitem>
    <para>
     the component id string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function adds the component id string to the supported list.
   The component can be referred from the alsa-lib.
   </para><para>

   Returns zero otherwise a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-card-file-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_file_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_file_add</refname>
 <refpurpose>
     add the file to the file list of the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_file_add </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     file pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function adds the file to the file linked-list of the card.
   This linked-list is used to keep tracking the connection state,
   and to avoid the release of busy resources by hotplug.
   </para><para>

   Returns zero or a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-card-file-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_card_file_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_card_file_remove</refname>
 <refpurpose>
     remove the file from the file list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_card_file_remove </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     file pointer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function removes the file formerly added to the card via
   <function>snd_card_file_add</function> function.
   If all files are removed and <function>snd_card_free_when_closed</function> was
   called beforehand, it processes the pending release of
   resources.
   </para><para>

   Returns zero or a negative error code.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-power-wait">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_power_wait</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_power_wait</refname>
 <refpurpose>
     wait until the power-state is changed.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_power_wait </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>unsigned int <parameter>power_state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     soundcard structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>power_state</parameter></term>
   <listitem>
    <para>
     expected power state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Waits until the power-state is changed.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the power lock must be active before call.
</para>
</refsect1>
</refentry>

<!-- sound/core/isadma.c -->
<refentry id="API-snd-dma-program">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_program</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_program</refname>
 <refpurpose>
  program an ISA DMA transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_dma_program </function></funcdef>
   <paramdef>unsigned long <parameter>dma</parameter></paramdef>
   <paramdef>unsigned long <parameter>addr</parameter></paramdef>
   <paramdef>unsigned int <parameter>size</parameter></paramdef>
   <paramdef>unsigned short <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dma</parameter></term>
   <listitem>
    <para>
     the dma number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addr</parameter></term>
   <listitem>
    <para>
     the physical address of the buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the DMA transfer size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the DMA transfer mode, DMA_MODE_XXX
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Programs an ISA DMA transfer for the given buffer.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_disable</refname>
 <refpurpose>
     stop the ISA DMA transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_dma_disable </function></funcdef>
   <paramdef>unsigned long <parameter>dma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dma</parameter></term>
   <listitem>
    <para>
     the dma number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Stops the ISA DMA transfer.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-pointer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_pointer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_pointer</refname>
 <refpurpose>
     return the current pointer to DMA transfer buffer in bytes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>snd_dma_pointer </function></funcdef>
   <paramdef>unsigned long <parameter>dma</parameter></paramdef>
   <paramdef>unsigned int <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dma</parameter></term>
   <listitem>
    <para>
     the dma number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the dma transfer size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the current pointer in DMA tranfer buffer in bytes
</para>
</refsect1>
</refentry>

<!-- sound/core/control.c -->
<refentry id="API-snd-ctl-new1">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_new1</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_new1</refname>
 <refpurpose>
  create a control instance from the template
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_kcontrol * <function>snd_ctl_new1 </function></funcdef>
   <paramdef>const struct snd_kcontrol_new * <parameter>ncontrol</parameter></paramdef>
   <paramdef>void * <parameter>private_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ncontrol</parameter></term>
   <listitem>
    <para>
     the initialization record
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>private_data</parameter></term>
   <listitem>
    <para>
     the private data to set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates a new struct snd_kcontrol instance and initialize from the given 
   template.  When the access field of ncontrol is 0, it's assumed as
   READWRITE access. When the count field is 0, it's assumes as one.
   </para><para>

   Returns the pointer of the newly generated instance, or NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-free-one">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_free_one</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_free_one</refname>
 <refpurpose>
     release the control instance
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_ctl_free_one </function></funcdef>
   <paramdef>struct snd_kcontrol * <parameter>kcontrol</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kcontrol</parameter></term>
   <listitem>
    <para>
     the control instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases the control instance created via <function>snd_ctl_new</function>
   or <function>snd_ctl_new1</function>.
   Don't call this after the control was added to the card.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_add</refname>
 <refpurpose>
     add the control instance to the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_add </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_kcontrol * <parameter>kcontrol</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kcontrol</parameter></term>
   <listitem>
    <para>
     the control instance to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Adds the control instance created via <function>snd_ctl_new</function> or
   <function>snd_ctl_new1</function> to the given card. Assigns also an unique
   numid used for fast search.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
   </para><para>

   It frees automatically the control which cannot be added.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_remove</refname>
 <refpurpose>
     remove the control from the card and release it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_remove </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_kcontrol * <parameter>kcontrol</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>kcontrol</parameter></term>
   <listitem>
    <para>
     the control instance to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes the control from the card and then releases the instance.
   You don't need to call <function>snd_ctl_free_one</function>. You must be in
   the write lock - down_write(&amp;card-&gt;controls_rwsem).
   </para><para>

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

<refentry id="API-snd-ctl-remove-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_remove_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_remove_id</refname>
 <refpurpose>
     remove the control of the given id and release it
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_remove_id </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_id * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the control id to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds the control instance with the given id, removes it from the
   card list and releases it.
   </para><para>

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

<refentry id="API-snd-ctl-rename-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_rename_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_rename_id</refname>
 <refpurpose>
     replace the id of a control on the card
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_ctl_rename_id </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_id * <parameter>src_id</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_id * <parameter>dst_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_id</parameter></term>
   <listitem>
    <para>
     the old id
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dst_id</parameter></term>
   <listitem>
    <para>
     the new id
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds the control with the old id from the card, and replaces the
   id with the new one.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-find-numid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_find_numid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_find_numid</refname>
 <refpurpose>
     find the control instance with the given number-id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_kcontrol * <function>snd_ctl_find_numid </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>unsigned int <parameter>numid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>numid</parameter></term>
   <listitem>
    <para>
     the number-id to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds the control instance with the given number-id from the card.
   </para><para>

   Returns the pointer of the instance if found, or NULL if not.
   </para><para>

   The caller must down card-&gt;controls_rwsem before calling this function
   (if the race condition can happen).
</para>
</refsect1>
</refentry>

<refentry id="API-snd-ctl-find-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_ctl_find_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_ctl_find_id</refname>
 <refpurpose>
     find the control instance with the given id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct snd_kcontrol * <function>snd_ctl_find_id </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>struct snd_ctl_elem_id * <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the id to search
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds the control instance with the given id from the card.
   </para><para>

   Returns the pointer of the instance if found, or NULL if not.
   </para><para>

   The caller must down card-&gt;controls_rwsem before calling this function
   (if the race condition can happen).
</para>
</refsect1>
</refentry>

<!-- sound/core/pcm_lib.c -->
<refentry id="API-snd-pcm-set-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_set_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_set_ops</refname>
 <refpurpose>
  set the PCM operators
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_set_ops </function></funcdef>
   <paramdef>struct snd_pcm * <parameter>pcm</parameter></paramdef>
   <paramdef>int <parameter>direction</parameter></paramdef>
   <paramdef>struct snd_pcm_ops * <parameter>ops</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     the pcm instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>direction</parameter></term>
   <listitem>
    <para>
     stream direction, SNDRV_PCM_STREAM_XXX
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     the operator table
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets the given PCM operators to the pcm instance.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-set-sync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_set_sync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_set_sync</refname>
 <refpurpose>
     set the PCM sync id
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_set_sync </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets the PCM sync identifier for the card.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-interval-refine">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_interval_refine</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_interval_refine</refname>
 <refpurpose>
     refine the interval value of configurator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_interval_refine </function></funcdef>
   <paramdef>struct snd_interval * <parameter>i</parameter></paramdef>
   <paramdef>const struct snd_interval * <parameter>v</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     the interval value to refine
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>v</parameter></term>
   <listitem>
    <para>
     the interval value to refer to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refines the interval value with the reference value.
   The interval is changed to the range satisfying both intervals.
   The interval status (min, max, integer, etc.) are evaluated.
   </para><para>

   Returns non-zero if the value is changed, zero if not changed.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-interval-ratnum">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_interval_ratnum</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_interval_ratnum</refname>
 <refpurpose>
     refine the interval value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_interval_ratnum </function></funcdef>
   <paramdef>struct snd_interval * <parameter>i</parameter></paramdef>
   <paramdef>unsigned int <parameter>rats_count</parameter></paramdef>
   <paramdef>struct snd_ratnum * <parameter>rats</parameter></paramdef>
   <paramdef>unsigned int * <parameter>nump</parameter></paramdef>
   <paramdef>unsigned int * <parameter>denp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     interval to refine
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rats_count</parameter></term>
   <listitem>
    <para>
     number of ratnum_t 
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rats</parameter></term>
   <listitem>
    <para>
     ratnum_t array
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nump</parameter></term>
   <listitem>
    <para>
     pointer to store the resultant numerator
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>denp</parameter></term>
   <listitem>
    <para>
     pointer to store the resultant denominator
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns non-zero if the value is changed, zero if not changed.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-interval-list">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_interval_list</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_interval_list</refname>
 <refpurpose>
     refine the interval value from the list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_interval_list </function></funcdef>
   <paramdef>struct snd_interval * <parameter>i</parameter></paramdef>
   <paramdef>unsigned int <parameter>count</parameter></paramdef>
   <paramdef>unsigned int * <parameter>list</parameter></paramdef>
   <paramdef>unsigned int <parameter>mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>i</parameter></term>
   <listitem>
    <para>
     the interval value to refine
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     the number of elements in the list
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>list</parameter></term>
   <listitem>
    <para>
     the value list
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mask</parameter></term>
   <listitem>
    <para>
     the bit-mask to evaluate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Refines the interval value from the list.
   When mask is non-zero, only the elements corresponding to bit 1 are
   evaluated.
   </para><para>

   Returns non-zero if the value is changed, zero if not changed.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-rule-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_rule_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_rule_add</refname>
 <refpurpose>
     add the hw-constraint rule
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_rule_add </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>int <parameter>var</parameter></paramdef>
   <paramdef>snd_pcm_hw_rule_func_t <parameter>func</parameter></paramdef>
   <paramdef>void * <parameter>private</parameter></paramdef>
   <paramdef>int <parameter>dep</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     the pcm runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     the variable to evaluate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>func</parameter></term>
   <listitem>
    <para>
     the evaluation function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>private</parameter></term>
   <listitem>
    <para>
     the private data pointer passed to function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dep</parameter></term>
   <listitem>
    <para>
     the dependent variables
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-integer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_integer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_integer</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_integer </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the integer constraint
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Apply the constraint of integer to an interval parameter.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-minmax">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_minmax</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_minmax</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_minmax </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>unsigned int <parameter>min</parameter></paramdef>
   <paramdef>unsigned int <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the range
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     the minimal value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     the maximal value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Apply the min/max range constraint to an interval parameter.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-list">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_list</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_list</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_list </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>struct snd_pcm_hw_constraint_list * <parameter>l</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the list constraint
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>l</parameter></term>
   <listitem>
    <para>
     list
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Apply the list of constraints to an interval parameter.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-ratnums">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_ratnums</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_ratnums</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_ratnums </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>struct snd_pcm_hw_constraint_ratnums * <parameter>r</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the ratnums constraint
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     struct snd_ratnums constriants
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-ratdens">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_ratdens</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_ratdens</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_ratdens </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>struct snd_pcm_hw_constraint_ratdens * <parameter>r</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the ratdens constraint
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     struct snd_ratdens constriants
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-msbits">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_msbits</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_msbits</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_msbits </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>unsigned int <parameter>width</parameter></paramdef>
   <paramdef>unsigned int <parameter>msbits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>width</parameter></term>
   <listitem>
    <para>
     sample bits width
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msbits</parameter></term>
   <listitem>
    <para>
     msbits width
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-step">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_step</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_step</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_step </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>unsigned long <parameter>step</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the step constraint
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>step</parameter></term>
   <listitem>
    <para>
     step size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-constraint-pow2">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_constraint_pow2</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_constraint_pow2</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_constraint_pow2 </function></funcdef>
   <paramdef>struct snd_pcm_runtime * <parameter>runtime</parameter></paramdef>
   <paramdef>unsigned int <parameter>cond</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>runtime</parameter></term>
   <listitem>
    <para>
     PCM runtime instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cond</parameter></term>
   <listitem>
    <para>
     condition bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     hw_params variable to apply the power-of-2 constraint
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-param-value">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_param_value</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_param_value</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_param_value </function></funcdef>
   <paramdef>const struct snd_pcm_hw_params * <parameter>params</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>int * <parameter>dir</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     the hw_params instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     parameter to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dir</parameter></term>
   <listitem>
    <para>
     pointer to the direction (-1,0,1) or NULL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return the value for field PAR if it's fixed in configuration space 
   defined by PARAMS. Return -EINVAL otherwise
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-param-first">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_param_first</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_param_first</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_param_first </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>pcm</parameter></paramdef>
   <paramdef>struct snd_pcm_hw_params * <parameter>params</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>int * <parameter>dir</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     PCM instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     the hw_params instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     parameter to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dir</parameter></term>
   <listitem>
    <para>
     pointer to the direction (-1,0,1) or NULL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Inside configuration space defined by PARAMS remove from PAR all 
   values &gt; minimum. Reduce configuration space accordingly.
   Return the minimum.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-hw-param-last">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_hw_param_last</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_hw_param_last</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_hw_param_last </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>pcm</parameter></paramdef>
   <paramdef>struct snd_pcm_hw_params * <parameter>params</parameter></paramdef>
   <paramdef>snd_pcm_hw_param_t <parameter>var</parameter></paramdef>
   <paramdef>int * <parameter>dir</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     PCM instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     the hw_params instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     parameter to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dir</parameter></term>
   <listitem>
    <para>
     pointer to the direction (-1,0,1) or NULL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Inside configuration space defined by PARAMS remove from PAR all 
   values &lt; maximum. Reduce configuration space accordingly.
   Return the maximum.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-lib-ioctl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_lib_ioctl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_lib_ioctl</refname>
 <refpurpose>
     a generic PCM ioctl callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_lib_ioctl </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>unsigned int <parameter>cmd</parameter></paramdef>
   <paramdef>void * <parameter>arg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     ioctl command
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>arg</parameter></term>
   <listitem>
    <para>
     ioctl argument
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Processes the generic ioctl commands for PCM.
   Can be passed as the ioctl callback for PCM ops.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-period-elapsed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_period_elapsed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_period_elapsed</refname>
 <refpurpose>
     update the pcm status for the next period
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_pcm_period_elapsed </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the pcm substream instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is called from the interrupt handler when the
   PCM has processed the period size.  It will update the current
   pointer, set up the tick, wake up sleepers, etc.
   </para><para>

   Even if more than one periods have elapsed since the last call, you
   have to call this only once.
</para>
</refsect1>
</refentry>

<!-- sound/core/hwdep.c -->
<refentry id="API-snd-hwdep-new">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_hwdep_new</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_hwdep_new</refname>
 <refpurpose>
  create a new hwdep instance
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_hwdep_new </function></funcdef>
   <paramdef>struct snd_card * <parameter>card</parameter></paramdef>
   <paramdef>char * <parameter>id</parameter></paramdef>
   <paramdef>int <parameter>device</parameter></paramdef>
   <paramdef>struct snd_hwdep ** <parameter>rhwdep</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>card</parameter></term>
   <listitem>
    <para>
     the card instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the id string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device index (zero-based)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rhwdep</parameter></term>
   <listitem>
    <para>
     the pointer to store the new hwdep instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Creates a new hwdep instance with the given index on the card.
   The callbacks (hwdep-&gt;ops) must be set on the returned instance
   after this call manually by the caller.
   </para><para>

   Returns zero if successful, or a negative error code on failure.
</para>
</refsect1>
</refentry>

<!-- sound/core/pcm_native.c -->
<refentry id="API-snd-pcm-stop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_stop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_stop</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_stop </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
   <paramdef>int <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the PCM substream instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     PCM state after stopping the stream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Try to stop all running streams in the substream group.
   The state of each stream is changed to the given value after that unconditionally.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_suspend</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_suspend </function></funcdef>
   <paramdef>struct snd_pcm_substream * <parameter>substream</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>substream</parameter></term>
   <listitem>
    <para>
     the PCM substream
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Trigger SUSPEND to all linked streams.
   After this call, all streams are changed to SUSPENDED state.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-pcm-suspend-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_pcm_suspend_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_pcm_suspend_all</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_pcm_suspend_all </function></funcdef>
   <paramdef>struct snd_pcm * <parameter>pcm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pcm</parameter></term>
   <listitem>
    <para>
     the PCM instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Trigger SUSPEND to all substreams in the given pcm.
   After this call, all streams are changed to SUSPENDED state.
</para>
</refsect1>
</refentry>

<!-- sound/core/memalloc.c -->
<refentry id="API-snd-malloc-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_malloc_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_malloc_pages</refname>
 <refpurpose>
  allocate pages with the given size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>snd_malloc_pages </function></funcdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>gfp_t <parameter>gfp_flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the size to allocate in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gfp_flags</parameter></term>
   <listitem>
    <para>
     the allocation conditions, GFP_XXX
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates the physically contiguous pages with the given size.
   </para><para>

   Returns the pointer of the buffer, or NULL if no enoguh memory.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-free-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_free_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_free_pages</refname>
 <refpurpose>
     release the pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_free_pages </function></funcdef>
   <paramdef>void * <parameter>ptr</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ptr</parameter></term>
   <listitem>
    <para>
     the buffer pointer to release
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the allocated buffer size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases the buffer allocated via <function>snd_malloc_pages</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-alloc-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_alloc_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_alloc_pages</refname>
 <refpurpose>
     allocate the buffer area according to the given type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_dma_alloc_pages </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>struct device * <parameter>device</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>struct snd_dma_buffer * <parameter>dmab</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the DMA buffer type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the buffer size to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dmab</parameter></term>
   <listitem>
    <para>
     buffer allocation record to store the allocated data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls the memory-allocator function for the corresponding
   buffer type.
   </para><para>

   Returns zero if the buffer with the given size is allocated successfuly,
   other a negative value at error.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-alloc-pages-fallback">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_alloc_pages_fallback</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_alloc_pages_fallback</refname>
 <refpurpose>
     allocate the buffer area according to the given type with fallback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_dma_alloc_pages_fallback </function></funcdef>
   <paramdef>int <parameter>type</parameter></paramdef>
   <paramdef>struct device * <parameter>device</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>struct snd_dma_buffer * <parameter>dmab</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     the DMA buffer type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>device</parameter></term>
   <listitem>
    <para>
     the device pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the buffer size to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dmab</parameter></term>
   <listitem>
    <para>
     buffer allocation record to store the allocated data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls the memory-allocator function for the corresponding
   buffer type.  When no space is left, this function reduces the size and
   tries to allocate again.  The size actually allocated is stored in
   res_size argument.
   </para><para>

   Returns zero if the buffer with the given size is allocated successfuly,
   other a negative value at error.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-free-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_free_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_free_pages</refname>
 <refpurpose>
     release the allocated buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>snd_dma_free_pages </function></funcdef>
   <paramdef>struct snd_dma_buffer * <parameter>dmab</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmab</parameter></term>
   <listitem>
    <para>
     the buffer allocation record to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases the allocated buffer via <function>snd_dma_alloc_pages</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-get-reserved-buf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_get_reserved_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_get_reserved_buf</refname>
 <refpurpose>
     get the reserved buffer for the given device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>snd_dma_get_reserved_buf </function></funcdef>
   <paramdef>struct snd_dma_buffer * <parameter>dmab</parameter></paramdef>
   <paramdef>unsigned int <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmab</parameter></term>
   <listitem>
    <para>
     the buffer allocation record to store
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the buffer id
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Looks for the reserved-buffer list and re-uses if the same buffer
   is found in the list.  When the buffer is found, it's removed from the free list.
   </para><para>

   Returns the size of buffer if the buffer is found, or zero if not found.
</para>
</refsect1>
</refentry>

<refentry id="API-snd-dma-reserve-buf">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>snd_dma_reserve_buf</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>snd_dma_reserve_buf</refname>
 <refpurpose>
     reserve the buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>snd_dma_reserve_buf </function></funcdef>
   <paramdef>struct snd_dma_buffer * <parameter>dmab</parameter></paramdef>
   <paramdef>unsigned int <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmab</parameter></term>
   <listitem>
    <para>
     the buffer to reserve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     the buffer id
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reserves the given buffer as a reserved buffer.
   </para><para>

   Returns zero if successful, or a negative code at error.
</para>
</refsect1>
</refentry>

<!-- FIXME: Removed for now since no structured comments in source
X!Isound/sound_firmware.c
-->
  </chapter>

  <chapter id="uart16x50">
     <title>16x50 UART Driver</title>
<!-- include/linux/serial_core.h -->
<refentry id="API-uart-handle-dcd-change">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_handle_dcd_change</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_handle_dcd_change</refname>
 <refpurpose>
  handle a change of carrier detect state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uart_handle_dcd_change </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
   <paramdef>unsigned int <parameter>status</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     uart_port structure for the open port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>status</parameter></term>
   <listitem>
    <para>
     new carrier detect status, nonzero if active
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-uart-handle-cts-change">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_handle_cts_change</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_handle_cts_change</refname>
 <refpurpose>
     handle a change of clear-to-send state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uart_handle_cts_change </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
   <paramdef>unsigned int <parameter>status</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     uart_port structure for the open port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>status</parameter></term>
   <listitem>
    <para>
     new clear to send status, nonzero if active
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/serial/serial_core.c -->
<refentry id="API-uart-update-timeout">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_update_timeout</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_update_timeout</refname>
 <refpurpose>
  update per-port FIFO timeout.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uart_update_timeout </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
   <paramdef>unsigned int <parameter>cflag</parameter></paramdef>
   <paramdef>unsigned int <parameter>baud</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     uart_port structure describing the port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cflag</parameter></term>
   <listitem>
    <para>
     termios cflag value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>baud</parameter></term>
   <listitem>
    <para>
     speed of the port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set the port FIFO timeout value.  The <parameter>cflag</parameter> value should
   reflect the actual hardware settings.
</para>
</refsect1>
</refentry>

<refentry id="API-uart-get-baud-rate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_get_baud_rate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_get_baud_rate</refname>
 <refpurpose>
     return baud rate for a particular port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>uart_get_baud_rate </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
   <paramdef>struct ktermios * <parameter>termios</parameter></paramdef>
   <paramdef>struct ktermios * <parameter>old</parameter></paramdef>
   <paramdef>unsigned int <parameter>min</parameter></paramdef>
   <paramdef>unsigned int <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     uart_port structure describing the port in question.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>termios</parameter></term>
   <listitem>
    <para>
     desired termios settings.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     old termios (or NULL)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     minimum acceptable baud rate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     maximum acceptable baud rate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Decode the termios structure into a numeric baud rate,
   taking account of the magic 38400 baud rate (with spd_*
   flags), and mapping the <constant>B0</constant> rate to 9600 baud.
   </para><para>

   If the new baud rate is invalid, try the old termios setting.
   If it's still invalid, we try 9600 baud.
   </para><para>

   Update the <parameter>termios</parameter> structure to reflect the baud rate
   we're actually going to be using.
</para>
</refsect1>
</refentry>

<refentry id="API-uart-get-divisor">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_get_divisor</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_get_divisor</refname>
 <refpurpose>
     return uart clock divisor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>uart_get_divisor </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
   <paramdef>unsigned int <parameter>baud</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     uart_port structure describing the port.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>baud</parameter></term>
   <listitem>
    <para>
     desired baud rate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calculate the uart clock divisor for the port.
</para>
</refsect1>
</refentry>

<refentry id="API-uart-register-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_register_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_register_driver</refname>
 <refpurpose>
     register a driver with the uart core layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>uart_register_driver </function></funcdef>
   <paramdef>struct uart_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     low level driver structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register a uart driver with the core driver.  We in turn register
   with the tty layer, and initialise the core driver per-port state.
   </para><para>

   We have a proc file in /proc/tty/driver which is named after the
   normal driver.
   </para><para>

   drv-&gt;port should be NULL, and the per-port structures should be
   registered using uart_add_one_port after this call has succeeded.
</para>
</refsect1>
</refentry>

<refentry id="API-uart-unregister-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_unregister_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_unregister_driver</refname>
 <refpurpose>
     remove a driver from the uart core layer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>uart_unregister_driver </function></funcdef>
   <paramdef>struct uart_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     low level driver structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove all references to a driver from the core driver.  The low
   level driver must have removed all its ports via the
   <function>uart_remove_one_port</function> if it registered them with <function>uart_add_one_port</function>.
   (ie, drv-&gt;port == NULL)
</para>
</refsect1>
</refentry>

<refentry id="API-uart-add-one-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_add_one_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_add_one_port</refname>
 <refpurpose>
     attach a driver-defined port structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>uart_add_one_port </function></funcdef>
   <paramdef>struct uart_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     pointer to the uart low level driver structure for this port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     uart port structure to use for this port.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This allows the driver to register its own uart_port structure
   with the core driver.  The main purpose is to allow the low
   level uart drivers to expand uart_port, rather than having yet
   more levels of structures.
</para>
</refsect1>
</refentry>

<refentry id="API-uart-remove-one-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>uart_remove_one_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>uart_remove_one_port</refname>
 <refpurpose>
     detach a driver defined port structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>uart_remove_one_port </function></funcdef>
   <paramdef>struct uart_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     pointer to the uart low level driver structure for this port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     uart port structure for this port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This unhooks (and hangs up) the specified port structure from the
   core driver.  No further calls will be made to the low-level code
   for this port.
</para>
</refsect1>
</refentry>

<!-- drivers/serial/8250.c -->
<refentry id="API-serial8250-suspend-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>serial8250_suspend_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>serial8250_suspend_port</refname>
 <refpurpose>
  suspend one serial port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>serial8250_suspend_port </function></funcdef>
   <paramdef>int <parameter>line</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>line</parameter></term>
   <listitem>
    <para>
     serial line number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Suspend one serial port.
</para>
</refsect1>
</refentry>

<refentry id="API-serial8250-resume-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>serial8250_resume_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>serial8250_resume_port</refname>
 <refpurpose>
     resume one serial port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>serial8250_resume_port </function></funcdef>
   <paramdef>int <parameter>line</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>line</parameter></term>
   <listitem>
    <para>
     serial line number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Resume one serial port.
</para>
</refsect1>
</refentry>

<refentry id="API-serial8250-register-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>serial8250_register_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>serial8250_register_port</refname>
 <refpurpose>
     register a serial port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>serial8250_register_port </function></funcdef>
   <paramdef>struct uart_port * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     serial port template
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Configure the serial port specified by the request. If the
   port exists and is in use, it is hung up and unregistered
   first.
   </para><para>

   The port is then probed and if necessary the IRQ is autodetected
   If this fails an error is returned.
   </para><para>

   On success the port is ready to use and the line number is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-serial8250-unregister-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>serial8250_unregister_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>serial8250_unregister_port</refname>
 <refpurpose>
     remove a 16x50 serial port at runtime
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>serial8250_unregister_port </function></funcdef>
   <paramdef>int <parameter>line</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>line</parameter></term>
   <listitem>
    <para>
     serial line number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove one serial port.  This may not be called from interrupt
   context.  We hand the port back to the our control.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="z85230">
     <title>Z85230 Support Library</title>
<!-- drivers/net/wan/z85230.c -->
<refentry id="API-z8530-interrupt">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_interrupt</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_interrupt</refname>
 <refpurpose>
  Handle an interrupt from a Z8530
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>irqreturn_t <function>z8530_interrupt </function></funcdef>
   <paramdef>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 number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev_id</parameter></term>
   <listitem>
    <para>
     The Z8530 device that is interrupting.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A Z85[2]30 device has stuck its hand in the air for attention.
   We scan both the channels on the chip for events and then call
   the channel specific call backs for each channel that has events.
   We have to use callback functions because the two channels can be
   in different modes.
   </para><para>

   Locking is done for the handlers. Note that locking is done
   at the chip level (the 5uS delay issue is per chip not per
   channel). c-&gt;lock for both channels points to dev-&gt;lock
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-sync-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_sync_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_sync_open</refname>
 <refpurpose>
     Open a Z8530 channel for PIO
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>z8530_sync_open </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct z8530_channel * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     The network interface we are using
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The Z8530 channel to open in synchronous PIO mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Switch a Z8530 into synchronous mode without DMA assist. We
   raise the RTS/DTR and commence network operation.
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-sync-close">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_sync_close</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_sync_close</refname>
 <refpurpose>
     Close a PIO Z8530 channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>z8530_sync_close </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct z8530_channel * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Network device to close
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     Z8530 channel to disassociate and move to idle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Close down a Z8530 interface and switch its interrupt handlers
   to discard future events.
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-sync-dma-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_sync_dma_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_sync_dma_open</refname>
 <refpurpose>
     Open a Z8530 for DMA I/O
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>z8530_sync_dma_open </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct z8530_channel * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     The network device to attach
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The Z8530 channel to configure in sync DMA mode.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set up a Z85x30 device for synchronous DMA in both directions. Two
   ISA DMA channels must be available for this to work. We assume ISA
   DMA driven I/O and PC limits on access.
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-sync-dma-close">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_sync_dma_close</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_sync_dma_close</refname>
 <refpurpose>
     Close down DMA I/O
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>z8530_sync_dma_close </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct z8530_channel * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Network device to detach
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     Z8530 channel to move into discard mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Shut down a DMA mode synchronous interface. Halt the DMA, and
   free the buffers.
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-sync-txdma-open">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_sync_txdma_open</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_sync_txdma_open</refname>
 <refpurpose>
     Open a Z8530 for TX driven DMA
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>z8530_sync_txdma_open </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct z8530_channel * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     The network device to attach
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The Z8530 channel to configure in sync DMA mode.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set up a Z85x30 device for synchronous DMA tranmission. One
   ISA DMA channel must be available for this to work. The receive
   side is run in PIO mode, but then it has the bigger FIFO.
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-sync-txdma-close">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_sync_txdma_close</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_sync_txdma_close</refname>
 <refpurpose>
     Close down a TX driven DMA channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>z8530_sync_txdma_close </function></funcdef>
   <paramdef>struct net_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct z8530_channel * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Network device to detach
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     Z8530 channel to move into discard mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Shut down a DMA/PIO split mode synchronous interface. Halt the DMA, 
   and  free the buffers.
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-describe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_describe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_describe</refname>
 <refpurpose>
     Uniformly describe a Z8530 port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>z8530_describe </function></funcdef>
   <paramdef>struct z8530_dev * <parameter>dev</parameter></paramdef>
   <paramdef>char * <parameter>mapping</parameter></paramdef>
   <paramdef>unsigned long <parameter>io</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Z8530 device to describe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mapping</parameter></term>
   <listitem>
    <para>
     string holding mapping type (eg <quote>I/O</quote> or <quote>Mem</quote>)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>io</parameter></term>
   <listitem>
    <para>
     the port value in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Describe a Z8530 in a standard format. We must pass the I/O as
   the port offset isnt predictable. The main reason for this function
   is to try and get a common format of report.
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_init</refname>
 <refpurpose>
     Initialise a Z8530 device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>z8530_init </function></funcdef>
   <paramdef>struct z8530_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Z8530 device to initialise.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Configure up a Z8530/Z85C30 or Z85230 chip. We check the device
   is present, identify the type and then program it to hopefully
   keep quite and behave. This matters a lot, a Z8530 in the wrong
   state will sometimes get into stupid modes generating 10Khz
   interrupt streams and the like.
   </para><para>

   We set the interrupt handler up to discard any events, in case
   we get them during reset or setp.
   </para><para>

   Return 0 for success, or a negative value indicating the problem
   in errno form.
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-shutdown">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_shutdown</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_shutdown</refname>
 <refpurpose>
     Shutdown a Z8530 device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>z8530_shutdown </function></funcdef>
   <paramdef>struct z8530_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     The Z8530 chip to shutdown
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   We set the interrupt handlers to silence any interrupts. We then 
   reset the chip and wait 100uS to be sure the reset completed. Just
   in case the caller then tries to do stuff.
   </para><para>

   This is called without the lock held
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-channel-load">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_channel_load</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_channel_load</refname>
 <refpurpose>
     Load channel data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>z8530_channel_load </function></funcdef>
   <paramdef>struct z8530_channel * <parameter>c</parameter></paramdef>
   <paramdef>u8 * <parameter>rtable</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     Z8530 channel to configure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rtable</parameter></term>
   <listitem>
    <para>
     table of register, value pairs
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>FIXME</title>
<para>
   ioctl to allow user uploaded tables
   </para><para>

   Load a Z8530 channel up from the system data. We use +16 to 
   indicate the <quote>prime</quote> registers. The value 255 terminates the
   table.
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-null-rx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_null_rx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_null_rx</refname>
 <refpurpose>
     Discard a packet
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>z8530_null_rx </function></funcdef>
   <paramdef>struct z8530_channel * <parameter>c</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The channel the packet arrived on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     The buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   We point the receive handler at this function when idle. Instead
   of syncppp processing the frames we get to throw them away.
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-queue-xmit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_queue_xmit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_queue_xmit</refname>
 <refpurpose>
     Queue a packet
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>z8530_queue_xmit </function></funcdef>
   <paramdef>struct z8530_channel * <parameter>c</parameter></paramdef>
   <paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The channel to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>skb</parameter></term>
   <listitem>
    <para>
     The packet to kick down the channel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Queue a packet for transmission. Because we have rather
   hard to hit interrupt latencies for the Z85230 per packet 
   even in DMA mode we do the flip to DMA buffer if needed here
   not in the IRQ.
   </para><para>

   Called from the network code. The lock is not held at this 
   point.
</para>
</refsect1>
</refentry>

<refentry id="API-z8530-get-stats">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>z8530_get_stats</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>z8530_get_stats</refname>
 <refpurpose>
     Get network statistics
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct net_device_stats * <function>z8530_get_stats </function></funcdef>
   <paramdef>struct z8530_channel * <parameter>c</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>c</parameter></term>
   <listitem>
    <para>
     The channel to use
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Get the statistics block. We keep the statistics in software as
   the chip doesn't do it for us.
   </para><para>

   Locking is ignored here - we could lock for a copy but its
   not likely to be that big an issue
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="fbdev">
     <title>Frame Buffer Library</title>

     <para>
       The frame buffer drivers depend heavily on four data structures.  
       These structures are declared in include/linux/fb.h.  They are 
       fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. 
       The last three can be made available to and from userland. 
     </para>

     <para>
       fb_info defines the current state of a particular video card. 
       Inside fb_info, there exists a fb_ops structure which is a 
       collection of needed functions to make fbdev and fbcon work.
       fb_info is only visible to the kernel.
     </para>

     <para>
       fb_var_screeninfo is used to describe the features of a video card 
       that are user defined.  With fb_var_screeninfo, things such as
       depth and the resolution may be defined.
     </para>

     <para>
       The next structure is fb_fix_screeninfo. This defines the 
       properties of a card that are created when a mode is set and can't 
       be changed otherwise.  A good example of this is the start of the 
       frame buffer memory.  This "locks" the address of the frame buffer
       memory, so that it cannot be changed or moved.
     </para>

     <para>
       The last structure is fb_monospecs. In the old API, there was 
       little importance for fb_monospecs. This allowed for forbidden things 
       such as setting a mode of 800x600 on a fix frequency monitor. With 
       the new API, fb_monospecs prevents such things, and if used 
       correctly, can prevent a monitor from being cooked.  fb_monospecs
       will not be useful until kernels 2.5.x.
     </para>

     <sect1><title>Frame Buffer Memory</title>
<!-- drivers/video/fbmem.c -->
<refentry id="API-register-framebuffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>register_framebuffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>register_framebuffer</refname>
 <refpurpose>
  registers a frame buffer device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>register_framebuffer </function></funcdef>
   <paramdef>struct fb_info * <parameter>fb_info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers a frame buffer device <parameter>fb_info</parameter>.
   </para><para>

   Returns negative errno on error, or zero for success.
</para>
</refsect1>
</refentry>

<refentry id="API-unregister-framebuffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>unregister_framebuffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>unregister_framebuffer</refname>
 <refpurpose>
     releases a frame buffer device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>unregister_framebuffer </function></funcdef>
   <paramdef>struct fb_info * <parameter>fb_info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregisters a frame buffer device <parameter>fb_info</parameter>.
   </para><para>

   Returns negative errno on error, or zero for success.
   </para><para>

   This function will also notify the framebuffer console
   to release the driver.
   </para><para>

   This is meant to be called within a driver's <function>module_exit</function>
   function. If this is called outside <function>module_exit</function>, ensure
   that the driver implements <function>fb_open</function> and <function>fb_release</function> to
   check that no processes are using the device.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-set-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_set_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_set_suspend</refname>
 <refpurpose>
     low level driver signals suspend
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_set_suspend </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>int <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     framebuffer affected
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     0 = resuming, !=0 = suspending
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is meant to be used by low level drivers to
   signal suspend/resume to the core &amp; clients.
   It must be called with the console semaphore held
</para>
</refsect1>
</refentry>

<refentry id="API-fb-get-options">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_get_options</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_get_options</refname>
 <refpurpose>
     get kernel boot parameters
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_get_options </function></funcdef>
   <paramdef>char * <parameter>name</parameter></paramdef>
   <paramdef>char ** <parameter>option</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     framebuffer name as it would appear in
     the boot parameter line
     (video=&lt;name&gt;:&lt;options&gt;)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>option</parameter></term>
   <listitem>
    <para>
     the option will be stored here
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   Needed to maintain backwards compatibility
</para>
</refsect1>
</refentry>

     </sect1>
<!--
     <sect1><title>Frame Buffer Console</title>
X!Edrivers/video/console/fbcon.c
     </sect1>
-->
     <sect1><title>Frame Buffer Colormap</title>
<!-- drivers/video/fbcmap.c -->
<refentry id="API-fb-alloc-cmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_alloc_cmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_alloc_cmap</refname>
 <refpurpose>
  allocate a colormap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_alloc_cmap </function></funcdef>
   <paramdef>struct fb_cmap * <parameter>cmap</parameter></paramdef>
   <paramdef>int <parameter>len</parameter></paramdef>
   <paramdef>int <parameter>transp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmap</parameter></term>
   <listitem>
    <para>
     frame buffer colormap structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     length of <parameter>cmap</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>transp</parameter></term>
   <listitem>
    <para>
     boolean, 1 if there is transparency, 0 otherwise
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates memory for a colormap <parameter>cmap</parameter>.  <parameter>len</parameter> is the
   number of entries in the palette.
   </para><para>

   Returns negative errno on error, or zero on success.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-dealloc-cmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_dealloc_cmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_dealloc_cmap</refname>
 <refpurpose>
     deallocate a colormap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_dealloc_cmap </function></funcdef>
   <paramdef>struct fb_cmap * <parameter>cmap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmap</parameter></term>
   <listitem>
    <para>
     frame buffer colormap structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Deallocates a colormap that was previously allocated with
   <function>fb_alloc_cmap</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-copy-cmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_copy_cmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_copy_cmap</refname>
 <refpurpose>
     copy a colormap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_copy_cmap </function></funcdef>
   <paramdef>const struct fb_cmap * <parameter>from</parameter></paramdef>
   <paramdef>struct fb_cmap * <parameter>to</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>from</parameter></term>
   <listitem>
    <para>
     frame buffer colormap structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>to</parameter></term>
   <listitem>
    <para>
     frame buffer colormap structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copy contents of colormap from <parameter>from</parameter> to <parameter>to</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-set-cmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_set_cmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_set_cmap</refname>
 <refpurpose>
     set the colormap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_set_cmap </function></funcdef>
   <paramdef>struct fb_cmap * <parameter>cmap</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmap</parameter></term>
   <listitem>
    <para>
     frame buffer colormap structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets the colormap <parameter>cmap</parameter> for a screen of device <parameter>info</parameter>.
   </para><para>

   Returns negative errno on error, or zero on success.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-default-cmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_default_cmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_default_cmap</refname>
 <refpurpose>
     get default colormap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct fb_cmap * <function>fb_default_cmap </function></funcdef>
   <paramdef>int <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     size of palette for a depth
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Gets the default colormap for a specific screen depth.  <parameter>len</parameter>
   is the size of the palette for a particular screen depth.
   </para><para>

   Returns pointer to a frame buffer colormap structure.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-invert-cmaps">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_invert_cmaps</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_invert_cmaps</refname>
 <refpurpose>
     invert all defaults colormaps
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_invert_cmaps </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Invert all default colormaps.
</para>
</refsect1>
</refentry>

     </sect1>
<!-- FIXME:
  drivers/video/fbgen.c has no docs, which stuffs up the sgml.  Comment
  out until somebody adds docs.  KAO
     <sect1><title>Frame Buffer Generic Functions</title>
X!Idrivers/video/fbgen.c
     </sect1>
KAO -->
     <sect1><title>Frame Buffer Video Mode Database</title>
<!-- drivers/video/modedb.c -->
<refentry id="API-fb-try-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_try_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_try_mode</refname>
 <refpurpose>
  test a video mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_try_mode </function></funcdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const struct fb_videomode * <parameter>mode</parameter></paramdef>
   <paramdef>unsigned int <parameter>bpp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     frame buffer user defined part of display
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     frame buffer video mode structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bpp</parameter></term>
   <listitem>
    <para>
     color depth in bits per pixel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Tries a video mode to test it's validity for device <parameter>info</parameter>.
   </para><para>

   Returns 1 on success.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-delete-videomode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_delete_videomode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_delete_videomode</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_delete_videomode </function></funcdef>
   <paramdef>const struct fb_videomode * <parameter>mode</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     videomode to remove
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   Will remove all matching mode entries
</para>
</refsect1>
</refentry>

<refentry id="API-fb-destroy-modelist">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_destroy_modelist</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_destroy_modelist</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_destroy_modelist </function></funcdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/video/modedb.c -->
<refentry id="API-fb-find-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_find_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_find_mode</refname>
 <refpurpose>
  finds a valid video mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_find_mode </function></funcdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const char * <parameter>mode_option</parameter></paramdef>
   <paramdef>const struct fb_videomode * <parameter>db</parameter></paramdef>
   <paramdef>unsigned int <parameter>dbsize</parameter></paramdef>
   <paramdef>const struct fb_videomode * <parameter>default_mode</parameter></paramdef>
   <paramdef>unsigned int <parameter>default_bpp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     frame buffer user defined part of display
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode_option</parameter></term>
   <listitem>
    <para>
     string video mode to find
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>db</parameter></term>
   <listitem>
    <para>
     video mode database
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dbsize</parameter></term>
   <listitem>
    <para>
     size of <parameter>db</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>default_mode</parameter></term>
   <listitem>
    <para>
     default video mode to fall back to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>default_bpp</parameter></term>
   <listitem>
    <para>
     default color depth in bits per pixel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds a suitable video mode, starting with the specified mode
   in <parameter>mode_option</parameter> with fallback to <parameter>default_mode</parameter>.  If
   <parameter>default_mode</parameter> fails, all modes in the video mode database will
   be tried.
   </para><para>

   Valid mode specifiers for <parameter>mode_option</parameter>:
   </para><para>

   &lt;xres&gt;x&lt;yres&gt;[M][R][-&lt;bpp&gt;][@&lt;refresh&gt;][i][m] or
   &lt;name&gt;[-&lt;bpp&gt;][@&lt;refresh&gt;]
   </para><para>

   with &lt;xres&gt;, &lt;yres&gt;, &lt;bpp&gt; and &lt;refresh&gt; decimal numbers and
   &lt;name&gt; a string.
   </para><para>

   If 'M' is present after yres (and before refresh/bpp if present),
   the function will compute the timings using VESA(tm) Coordinated
   Video Timings (CVT).  If 'R' is present after 'M', will compute with
   reduced blanking (for flatpanels).  If 'i' is present, compute
   interlaced mode.  If 'm' is present, add margins equal to 1.8%
   of xres rounded down to 8 pixels, and 1.8% of yres. The char
   'i' and 'm' must be after 'M' and 'R'. Example:
   </para><para>

   1024x768MR-8<parameter>60m</parameter> - Reduced blank with margins at 60Hz.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   The passed struct <parameter>var</parameter> is _not_ cleared!  This allows you
   to supply values for e.g. the grayscale and accel_flags fields.
   </para><para>

   Returns zero for failure, 1 if using specified <parameter>mode_option</parameter>,
   2 if using specified <parameter>mode_option</parameter> with an ignored refresh rate,
   3 if default mode is used, 4 if fall back to any valid mode.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-var-to-videomode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_var_to_videomode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_var_to_videomode</refname>
 <refpurpose>
     convert fb_var_screeninfo to fb_videomode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_var_to_videomode </function></funcdef>
   <paramdef>struct fb_videomode * <parameter>mode</parameter></paramdef>
   <paramdef>const struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_videomode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_var_screeninfo
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-fb-videomode-to-var">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_videomode_to_var</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_videomode_to_var</refname>
 <refpurpose>
     convert fb_videomode to fb_var_screeninfo
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_videomode_to_var </function></funcdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>const struct fb_videomode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_var_screeninfo
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_videomode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-fb-mode-is-equal">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_mode_is_equal</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_mode_is_equal</refname>
 <refpurpose>
     compare 2 videomodes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_mode_is_equal </function></funcdef>
   <paramdef>const struct fb_videomode * <parameter>mode1</parameter></paramdef>
   <paramdef>const struct fb_videomode * <parameter>mode2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode1</parameter></term>
   <listitem>
    <para>
     first videomode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode2</parameter></term>
   <listitem>
    <para>
     second videomode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   1 if equal, 0 if not
</para>
</refsect1>
</refentry>

<refentry id="API-fb-find-best-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_find_best_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_find_best_mode</refname>
 <refpurpose>
     find best matching videomode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct fb_videomode * <function>fb_find_best_mode </function></funcdef>
   <paramdef>const struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_var_screeninfo
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     pointer to struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   struct fb_videomode, NULL if none found
</para>
</refsect1>
<refsect1>
<title>IMPORTANT</title>
<para>
   This function assumes that all modelist entries in
   info-&gt;modelist are valid.
</para>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   Finds best matching videomode which has an equal or greater dimension than
   var-&gt;xres and var-&gt;yres.  If more than 1 videomode is found, will return
   the videomode with the highest refresh rate
</para>
</refsect1>
</refentry>

<refentry id="API-fb-find-nearest-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_find_nearest_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_find_nearest_mode</refname>
 <refpurpose>
     find closest videomode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct fb_videomode * <function>fb_find_nearest_mode </function></funcdef>
   <paramdef>const struct fb_videomode * <parameter>mode</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_videomode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     pointer to modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds best matching videomode, smaller or greater in dimension.
   If more than 1 videomode is found, will return the videomode with
   the closest refresh rate.
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds best matching videomode, smaller or greater in dimension.
   If more than 1 videomode is found, will return the videomode with
   the closest refresh rate.
</para>
</refsect1>
</refentry>

<refentry id="API-fb-match-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_match_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_match_mode</refname>
 <refpurpose>
     find a videomode which exactly matches the timings in var
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const struct fb_videomode * <function>fb_match_mode </function></funcdef>
   <paramdef>const struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     pointer to struct fb_var_screeninfo
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     pointer to struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   struct fb_videomode, NULL if none found
</para>
</refsect1>
</refentry>

<refentry id="API-fb-add-videomode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_add_videomode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_add_videomode</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>fb_add_videomode </function></funcdef>
   <paramdef>const struct fb_videomode * <parameter>mode</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     videomode to add
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>
   Will only add unmatched mode entries
</para>
</refsect1>
</refentry>

<refentry id="API-fb-videomode-to-modelist">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>fb_videomode_to_modelist</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>fb_videomode_to_modelist</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>fb_videomode_to_modelist </function></funcdef>
   <paramdef>const struct fb_videomode * <parameter>modedb</parameter></paramdef>
   <paramdef>int <parameter>num</parameter></paramdef>
   <paramdef>struct list_head * <parameter>head</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>modedb</parameter></term>
   <listitem>
    <para>
     array of struct fb_videomode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num</parameter></term>
   <listitem>
    <para>
     number of entries in array
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>head</parameter></term>
   <listitem>
    <para>
     struct list_head of modelist
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Frame Buffer Macintosh Video Mode Database</title>
<!-- drivers/video/macmodes.c -->
<refentry id="API-mac-vmode-to-var">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mac_vmode_to_var</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mac_vmode_to_var</refname>
 <refpurpose>
  converts vmode/cmode pair to var structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mac_vmode_to_var </function></funcdef>
   <paramdef>int <parameter>vmode</parameter></paramdef>
   <paramdef>int <parameter>cmode</parameter></paramdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vmode</parameter></term>
   <listitem>
    <para>
     MacOS video mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmode</parameter></term>
   <listitem>
    <para>
     MacOS color mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     frame buffer video mode structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Converts a MacOS vmode/cmode pair to a frame buffer video
   mode structure.
   </para><para>

   Returns negative errno on error, or zero for success.
</para>
</refsect1>
</refentry>

<refentry id="API-mac-map-monitor-sense">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mac_map_monitor_sense</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mac_map_monitor_sense</refname>
 <refpurpose>
     Convert monitor sense to vmode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mac_map_monitor_sense </function></funcdef>
   <paramdef>int <parameter>sense</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sense</parameter></term>
   <listitem>
    <para>
     Macintosh monitor sense number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Converts a Macintosh monitor sense number to a MacOS
   vmode number.
   </para><para>

   Returns MacOS vmode video mode number.
</para>
</refsect1>
</refentry>

<refentry id="API-mac-find-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mac_find_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mac_find_mode</refname>
 <refpurpose>
     find a video mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mac_find_mode </function></funcdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const char * <parameter>mode_option</parameter></paramdef>
   <paramdef>unsigned int <parameter>default_bpp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     frame buffer user defined part of display
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     frame buffer info structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode_option</parameter></term>
   <listitem>
    <para>
     video mode name (see mac_modedb[])
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>default_bpp</parameter></term>
   <listitem>
    <para>
     default color depth in bits per pixel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finds a suitable video mode.  Tries to set mode specified
   by <parameter>mode_option</parameter>.  If the name of the wanted mode begins with
   'mac', the Mac video mode database will be used, otherwise it
   will fall back to the standard video mode database.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   Function marked as __init and can only be used during
   system boot.
   </para><para>

   Returns error code from fb_find_mode (see fb_find_mode
   function).
</para>
</refsect1>
</refentry>

     </sect1>
     <sect1><title>Frame Buffer Fonts</title>
        <para>
           Refer to the file drivers/video/console/fonts.c for more information.
        </para>
<!-- FIXME: Removed for now since no structured comments in source
X!Idrivers/video/console/fonts.c
-->
     </sect1>
  </chapter>

  <chapter id="input_subsystem">
     <title>Input Subsystem</title>
<!-- include/linux/input.h -->
<refentry id="API-struct-ff-replay">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct ff_replay</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct ff_replay</refname>
 <refpurpose>
  defines scheduling of the force-feedback effect
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct ff_replay {
  __u16 length;
  __u16 delay;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>length</term>
      <listitem><para>
duration of the effect
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>delay</term>
      <listitem><para>
delay before effect should start playing
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-ff-trigger">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct ff_trigger</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct ff_trigger</refname>
 <refpurpose>
     defines what triggers the force-feedback effect
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct ff_trigger {
  __u16 button;
  __u16 interval;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>button</term>
      <listitem><para>
   number of the button triggering the effect
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>interval</term>
      <listitem><para>
   controls how soon the effect can be re-triggered
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-ff-envelope">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct ff_envelope</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct ff_envelope</refname>
 <refpurpose>
     generic force-feedback effect envelope
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct ff_envelope {
  __u16 attack_length;
  __u16 attack_level;
  __u16 fade_length;
  __u16 fade_level;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>attack_length</term>
      <listitem><para>
   duration of the attack (ms)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>attack_level</term>
      <listitem><para>
   level at the beginning of the attack
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fade_length</term>
      <listitem><para>
   duration of fade (ms)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fade_level</term>
      <listitem><para>
   level at the end of fade
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   The <parameter>attack_level</parameter> and <parameter>fade_level</parameter> are absolute values; when applying
   envelope force-feedback core will convert to positive/negative
   value based on polarity of the default level of the effect.
   Valid range for the attack and fade levels is 0x0000 - 0x7fff
</para>
</refsect1>
</refentry>

<refentry id="API-struct-ff-constant-effect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct ff_constant_effect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct ff_constant_effect</refname>
 <refpurpose>
     defines parameters of a constant force-feedback effect
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct ff_constant_effect {
  __s16 level;
  struct ff_envelope envelope;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>level</term>
      <listitem><para>
   strength of the effect; may be negative
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>envelope</term>
      <listitem><para>
   envelope data
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-ff-ramp-effect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct ff_ramp_effect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct ff_ramp_effect</refname>
 <refpurpose>
     defines parameters of a ramp force-feedback effect
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct ff_ramp_effect {
  __s16 start_level;
  __s16 end_level;
  struct ff_envelope envelope;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>start_level</term>
      <listitem><para>
   beginning strength of the effect; may be negative
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>end_level</term>
      <listitem><para>
   final strength of the effect; may be negative
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>envelope</term>
      <listitem><para>
   envelope data
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-ff-condition-effect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct ff_condition_effect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct ff_condition_effect</refname>
 <refpurpose>
     defines a spring or friction force-feedback effect
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct ff_condition_effect {
  __u16 right_saturation;
  __u16 left_saturation;
  __s16 right_coeff;
  __s16 left_coeff;
  __u16 deadband;
  __s16 center;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>right_saturation</term>
      <listitem><para>
   maximum level when joystick moved all way to the right
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>left_saturation</term>
      <listitem><para>
   same for the left side
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>right_coeff</term>
      <listitem><para>
   controls how fast the force grows when the joystick moves
   to the right
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>left_coeff</term>
      <listitem><para>
   same for the left side
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>deadband</term>
      <listitem><para>
   size of the dead zone, where no force is produced
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>center</term>
      <listitem><para>
   position of the dead zone
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-ff-periodic-effect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct ff_periodic_effect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct ff_periodic_effect</refname>
 <refpurpose>
     defines parameters of a periodic force-feedback effect
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct ff_periodic_effect {
  __u16 waveform;
  __u16 period;
  __s16 magnitude;
  __s16 offset;
  __u16 phase;
  struct ff_envelope envelope;
  __u32 custom_len;
  __s16 * custom_data;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>waveform</term>
      <listitem><para>
   kind of the effect (wave)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>period</term>
      <listitem><para>
   period of the wave (ms)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>magnitude</term>
      <listitem><para>
   peak value
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>offset</term>
      <listitem><para>
   mean value of the wave (roughly)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>phase</term>
      <listitem><para>
   'horizontal' shift
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>envelope</term>
      <listitem><para>
   envelope data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>custom_len</term>
      <listitem><para>
   number of samples (FF_CUSTOM only)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>custom_data</term>
      <listitem><para>
   buffer of samples (FF_CUSTOM only)
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Known waveforms - FF_SQUARE, FF_TRIANGLE, FF_SINE, FF_SAW_UP,
   FF_SAW_DOWN, FF_CUSTOM. The exact syntax FF_CUSTOM is undefined
   for the time being as no driver supports it yet.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the data pointed by custom_data is copied by the driver.
   You can therefore dispose of the memory after the upload/update.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-ff-rumble-effect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct ff_rumble_effect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct ff_rumble_effect</refname>
 <refpurpose>
     defines parameters of a periodic force-feedback effect
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct ff_rumble_effect {
  __u16 strong_magnitude;
  __u16 weak_magnitude;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>strong_magnitude</term>
      <listitem><para>
   magnitude of the heavy motor
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>weak_magnitude</term>
      <listitem><para>
   magnitude of the light one
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Some rumble pads have two motors of different weight. Strong_magnitude
   represents the magnitude of the vibration generated by the heavy one.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-ff-effect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct ff_effect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct ff_effect</refname>
 <refpurpose>
     defines force feedback effect
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct ff_effect {
  __u16 type;
  __s16 id;
  __u16 direction;
  struct ff_trigger trigger;
  struct ff_replay replay;
  union u;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>type</term>
      <listitem><para>
   type of the effect (FF_CONSTANT, FF_PERIODIC, FF_RAMP, FF_SPRING,
   FF_FRICTION, FF_DAMPER, FF_RUMBLE, FF_INERTIA, or FF_CUSTOM)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id</term>
      <listitem><para>
   an unique id assigned to an effect
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>direction</term>
      <listitem><para>
   direction of the effect
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>trigger</term>
      <listitem><para>
   trigger conditions (struct ff_trigger)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>replay</term>
      <listitem><para>
   scheduling of the effect (struct ff_replay)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>u</term>
      <listitem><para>
   effect-specific structure (one of ff_constant_effect, ff_ramp_effect,
   ff_periodic_effect, ff_condition_effect, ff_rumble_effect) further
   defining effect parameters
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This structure is sent through ioctl from the application to the driver.
   To create a new effect aplication should set its <parameter>id</parameter> to -1; the kernel
   will return assigned <parameter>id</parameter> which can later be used to update or delete
   this effect.
</para>
</refsect1>
<refsect1>
<title>Direction of the effect is encoded as follows</title>
<para>
   0 deg -&gt; 0x0000 (down)
   90 deg -&gt; 0x4000 (left)
   180 deg -&gt; 0x8000 (up)
   270 deg -&gt; 0xC000 (right)
</para>
</refsect1>
</refentry>

<refentry id="API-struct-input-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct input_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct input_handler</refname>
 <refpurpose>
     implements one of interfaces for input devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct input_handler {
  void * private;
  void (* event) (struct input_handle *handle, unsigned int type, unsigned int code, int value);
  int (* connect) (struct input_handler *handler, struct input_dev *dev, const struct input_device_id *id);
  void (* disconnect) (struct input_handle *handle);
  void (* start) (struct input_handle *handle);
  const struct file_operations * fops;
  int minor;
  const char * name;
  const struct input_device_id * id_table;
  const struct input_device_id * blacklist;
  struct list_head h_list;
  struct list_head node;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>private</term>
      <listitem><para>
   driver-specific data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>event</term>
      <listitem><para>
   event handler
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connect</term>
      <listitem><para>
   called when attaching a handler to an input device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>disconnect</term>
      <listitem><para>
   disconnects a handler from input device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>start</term>
      <listitem><para>
   starts handler for given handle. This function is called by
   input core right after <function>connect</function> method and also when a process
   that <quote>grabbed</quote> a device releases it
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fops</term>
      <listitem><para>
   file operations this driver implements
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>minor</term>
      <listitem><para>
   beginning of range of 32 minors for devices this driver
   can provide
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name</term>
      <listitem><para>
   name of the handler, to be shown in /proc/bus/input/handlers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id_table</term>
      <listitem><para>
   pointer to a table of input_device_ids this driver can
   handle
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>blacklist</term>
      <listitem><para>
   prointer to a table of input_device_ids this driver should
   ignore even if they match <parameter>id_table</parameter>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>h_list</term>
      <listitem><para>
   list of input handles associated with the handler
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>node</term>
      <listitem><para>
   for placing the driver onto input_handler_list
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-ff-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct ff_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct ff_device</refname>
 <refpurpose>
     force-feedback part of an input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct ff_device {
  int (* upload) (struct input_dev *dev, struct ff_effect *effect,struct ff_effect *old);
  int (* erase) (struct input_dev *dev, int effect_id);
  int (* playback) (struct input_dev *dev, int effect_id, int value);
  void (* set_gain) (struct input_dev *dev, u16 gain);
  void (* set_autocenter) (struct input_dev *dev, u16 magnitude);
  void (* destroy) (struct ff_device *);
  void * private;
  unsigned long ffbit[NBITS(FF_MAX)];
  struct mutex mutex;
  int max_effects;
  struct ff_effect * effects;
  struct file * effect_owners[];
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>upload</term>
      <listitem><para>
   Called to upload an new effect into device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>erase</term>
      <listitem><para>
   Called to erase an effect from device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>playback</term>
      <listitem><para>
   Called to request device to start playing specified effect
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_gain</term>
      <listitem><para>
   Called to set specified gain
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_autocenter</term>
      <listitem><para>
   Called to auto-center device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>destroy</term>
      <listitem><para>
   called by input core when parent input device is being
   destroyed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>private</term>
      <listitem><para>
   driver-specific data, will be freed automatically
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ffbit[NBITS(FF_MAX)]</term>
      <listitem><para>
   bitmap of force feedback capabilities truly supported by
   device (not emulated like ones in input_dev-&gt;ffbit)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mutex</term>
      <listitem><para>
   mutex for serializing access to the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_effects</term>
      <listitem><para>
   maximum number of effects supported by device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>effects</term>
      <listitem><para>
   pointer to an array of effects currently loaded into device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>effect_owners[]</term>
      <listitem><para>
   array of effect owners; when file handle owning
   an effect gets closed the effcet is automatically erased
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Every force-feedback device must implement <function>upload</function> and <function>playback</function>
   methods; <function>erase</function> is optional. <function>set_gain</function> and <function>set_autocenter</function> need
   only be implemented if driver sets up FF_GAIN and FF_AUTOCENTER
   bits.
</para>
</refsect1>
</refentry>

<!-- drivers/input/input.c -->
<refentry id="API-input-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_event</refname>
 <refpurpose>
  report new input event
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_event </function></funcdef>
   <paramdef>struct input_dev * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>type</parameter></paramdef>
   <paramdef>unsigned int <parameter>code</parameter></paramdef>
   <paramdef>int <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device that generated the event
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of the event
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>code</parameter></term>
   <listitem>
    <para>
     event code
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     value of the event
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should be used by drivers implementing various input devices
   See also <function>input_inject_event</function>
</para>
</refsect1>
</refentry>

<refentry id="API-input-inject-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_inject_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_inject_event</refname>
 <refpurpose>
     send input event from input handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_inject_event </function></funcdef>
   <paramdef>struct input_handle * <parameter>handle</parameter></paramdef>
   <paramdef>unsigned int <parameter>type</parameter></paramdef>
   <paramdef>unsigned int <parameter>code</parameter></paramdef>
   <paramdef>int <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     input handle to send event through
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of the event
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>code</parameter></term>
   <listitem>
    <para>
     event code
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     value of the event
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Similar to <function>input_event</function> but will ignore event if device is <quote>grabbed</quote> and handle
   injecting event is not the one that owns the device.
</para>
</refsect1>
</refentry>

<refentry id="API-input-allocate-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_allocate_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_allocate_device</refname>
 <refpurpose>
     allocate memory for new input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct input_dev * <function>input_allocate_device </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Returns prepared struct input_dev or NULL.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   Use <function>input_free_device</function> to free devices that have not been
   registered; <function>input_unregister_device</function> should be used for already
   registered devices.
</para>
</refsect1>
</refentry>

<refentry id="API-input-free-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_free_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_free_device</refname>
 <refpurpose>
     free memory occupied by input_dev structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_free_device </function></funcdef>
   <paramdef>struct input_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should only be used if <function>input_register_device</function>
   was not called yet or if it failed. Once device was registered
   use <function>input_unregister_device</function> and memory will be freed once last
   refrence to the device is dropped.
   </para><para>

   Device should be allocated by <function>input_allocate_device</function>.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   If there are references to the input device then memory
   will not be freed until last reference is dropped.
</para>
</refsect1>
</refentry>

<refentry id="API-input-set-capability">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_set_capability</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_set_capability</refname>
 <refpurpose>
     mark device as capable of a certain event
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_set_capability </function></funcdef>
   <paramdef>struct input_dev * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>type</parameter></paramdef>
   <paramdef>unsigned int <parameter>code</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device that is capable of emitting or accepting event
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of the event (EV_KEY, EV_REL, etc...)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>code</parameter></term>
   <listitem>
    <para>
     event code
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   In addition to setting up corresponding bit in appropriate capability
   bitmap the function also adjusts dev-&gt;evbit.
</para>
</refsect1>
</refentry>

<!-- drivers/input/ff-core.c -->
<refentry id="API-input-ff-upload">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_upload</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_upload</refname>
 <refpurpose>
  upload effect into force-feedback device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_ff_upload </function></funcdef>
   <paramdef>struct input_dev * <parameter>dev</parameter></paramdef>
   <paramdef>struct ff_effect * <parameter>effect</parameter></paramdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>effect</parameter></term>
   <listitem>
    <para>
     effect to be uploaded
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     owner of the effect
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-input-ff-erase">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_erase</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_erase</refname>
 <refpurpose>
     erase a force-feedback effect from device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_ff_erase </function></funcdef>
   <paramdef>struct input_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>effect_id</parameter></paramdef>
   <paramdef>struct file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device to erase effect from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>effect_id</parameter></term>
   <listitem>
    <para>
     id of the ffect to be erased
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     purported owner of the request
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function erases a force-feedback effect from specified device.
   The effect will only be erased if it was uploaded through the same
   file handle that is requesting erase.
</para>
</refsect1>
</refentry>

<refentry id="API-input-ff-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_event</refname>
 <refpurpose>
     generic handler for force-feedback events
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_ff_event </function></funcdef>
   <paramdef>struct input_dev * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>type</parameter></paramdef>
   <paramdef>unsigned int <parameter>code</parameter></paramdef>
   <paramdef>int <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device to send the effect to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     event type (anything but EV_FF is ignored)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>code</parameter></term>
   <listitem>
    <para>
     event code
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     event value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-input-ff-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_create</refname>
 <refpurpose>
     create force-feedback device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_ff_create </function></funcdef>
   <paramdef>struct input_dev * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>max_effects</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device supporting force-feedback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_effects</parameter></term>
   <listitem>
    <para>
     maximum number of effects supported by the device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function allocates all necessary memory for a force feedback
   portion of an input device and installs all default handlers.
   <parameter>dev</parameter>-&gt;ffbit should be already set up before calling this function.
   Once ff device is created you need to setup its upload, erase,
   playback and other handlers before registering input device
</para>
</refsect1>
</refentry>

<refentry id="API-input-ff-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_destroy</refname>
 <refpurpose>
     frees force feedback portion of input device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>input_ff_destroy </function></funcdef>
   <paramdef>struct input_dev * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device supporting force feedback
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is only needed in error path as input core will
   automatically free force feedback structures when device is
   destroyed.
</para>
</refsect1>
</refentry>

<!-- drivers/input/ff-memless.c -->
<refentry id="API-input-ff-create-memless">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>input_ff_create_memless</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>input_ff_create_memless</refname>
 <refpurpose>
  create memoryless force-feedback device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>input_ff_create_memless </function></funcdef>
   <paramdef>struct input_dev * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>int (*<parameter>play_effect</parameter>)
     <funcparams>struct input_dev *, void *, struct ff_effect *</funcparams></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     input device supporting force-feedback
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     driver-specific data to be passed into <parameter>play_effect</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>play_effect</parameter></term>
   <listitem>
    <para>
     driver-specific method for playing FF effect
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

  </chapter>

  <chapter id="spi">
      <title>Serial Peripheral Interface (SPI)</title>
  <para>
	SPI is the "Serial Peripheral Interface", widely used with
	embedded systems because it is a simple and efficient
	interface:  basically a multiplexed shift register.
	Its three signal wires hold a clock (SCK, often in the range
	of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and
	a "Master In, Slave Out" (MISO) data line.
	SPI is a full duplex protocol; for each bit shifted out the
	MOSI line (one per clock) another is shifted in on the MISO line.
	Those bits are assembled into words of various sizes on the
	way to and from system memory.
	An additional chipselect line is usually active-low (nCS);
	four signals are normally used for each peripheral, plus
	sometimes an interrupt.
  </para>
  <para>
	The SPI bus facilities listed here provide a generalized
	interface to declare SPI busses and devices, manage them
	according to the standard Linux driver model, and perform
	input/output operations.
	At this time, only "master" side interfaces are supported,
	where Linux talks to SPI peripherals and does not implement
	such a peripheral itself.
	(Interfaces to support implementing SPI slaves would
	necessarily look different.)
  </para>
  <para>
	The programming interface is structured around two kinds of driver,
	and two kinds of device.
	A "Controller Driver" abstracts the controller hardware, which may
	be as simple as a set of GPIO pins or as complex as a pair of FIFOs
	connected to dual DMA engines on the other side of the SPI shift
	register (maximizing throughput).  Such drivers bridge between
	whatever bus they sit on (often the platform bus) and SPI, and
	expose the SPI side of their device as a
	<structname>struct spi_master</structname>.
	SPI devices are children of that master, represented as a
	<structname>struct spi_device</structname> and manufactured from
	<structname>struct spi_board_info</structname> descriptors which
	are usually provided by board-specific initialization code.
	A <structname>struct spi_driver</structname> is called a
	"Protocol Driver", and is bound to a spi_device using normal
	driver model calls.
  </para>
  <para>
	The I/O model is a set of queued messages.  Protocol drivers
	submit one or more <structname>struct spi_message</structname>
	objects, which are processed and completed asynchronously.
	(There are synchronous wrappers, however.)  Messages are
	built from one or more <structname>struct spi_transfer</structname>
	objects, each of which wraps a full duplex SPI transfer.
	A variety of protocol tweaking options are needed, because
	different chips adopt very different policies for how they
	use the bits transferred with SPI.
  </para>
<!-- include/linux/spi/spi.h -->
<refentry id="API-struct-spi-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_device</refname>
 <refpurpose>
  Master side proxy for an SPI slave device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_device {
  struct device dev;
  struct spi_master * master;
  u32 max_speed_hz;
  u8 chip_select;
  u8 mode;
#define SPI_CPHA	0x01
#define SPI_CPOL	0x02
#define SPI_MODE_0	(0|0)
#define SPI_MODE_1	(0|SPI_CPHA)
#define SPI_MODE_2	(SPI_CPOL|0)
#define SPI_MODE_3	(SPI_CPOL|SPI_CPHA)
#define SPI_CS_HIGH	0x04
#define SPI_LSB_FIRST	0x08
#define SPI_3WIRE	0x10
#define SPI_LOOP	0x20
  u8 bits_per_word;
  int irq;
  void * controller_state;
  void * controller_data;
  const char * modalias;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
Driver model representation of the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>master</term>
      <listitem><para>
SPI controller used with the device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_speed_hz</term>
      <listitem><para>
Maximum clock rate to be used with this chip
(on this board); may be changed by the device's driver.
The spi_transfer.speed_hz can override this for each transfer.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>chip_select</term>
      <listitem><para>
Chipselect, distinguishing chips handled by <parameter>master</parameter>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode</term>
      <listitem><para>
The spi mode defines how data is clocked out and in.
This may be changed by the device's driver.
The <quote>active low</quote> default for chipselect mode can be overridden
(by specifying SPI_CS_HIGH) as can the <quote>MSB first</quote> default for
each word in a transfer (by specifying SPI_LSB_FIRST).
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bits_per_word</term>
      <listitem><para>
Data transfers involve one or more words; word sizes
like eight or 12 bits are common.  In-memory wordsizes are
powers of two bytes (e.g. 20 bit samples use 32 bits).
This may be changed by the device's driver, or left at the
default (0) indicating protocol words are eight bit bytes.
The spi_transfer.bits_per_word can override this for each transfer.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>irq</term>
      <listitem><para>
Negative, or the number passed to <function>request_irq</function> to receive
interrupts from this device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>controller_state</term>
      <listitem><para>
Controller's runtime state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>controller_data</term>
      <listitem><para>
Board-specific definitions for controller, such as
FIFO initialization parameters; from board_info.controller_data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>modalias</term>
      <listitem><para>
Name of the driver to use with this device, or an alias
for that name.  This appears in the sysfs <quote>modalias</quote> attribute
for driver coldplugging, and in uevents used for hotplugging
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   A <parameter>spi_device</parameter> is used to interchange data between an SPI slave
   (usually a discrete chip) and CPU memory.
   </para><para>

   In <parameter>dev</parameter>, the platform_data is used to hold information about this
   device that's meaningful to the device's protocol driver, but not
   to its controller.  One example might be an identifier for a chip
   variant with slightly different functionality; another might be
   information about how this particular board wires the chip's pins.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-spi-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_driver</refname>
 <refpurpose>
     Host side <quote>protocol</quote> driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_driver {
  int (* probe) (struct spi_device *spi);
  int (* remove) (struct spi_device *spi);
  void (* shutdown) (struct spi_device *spi);
  int (* suspend) (struct spi_device *spi, pm_message_t mesg);
  int (* resume) (struct spi_device *spi);
  struct device_driver driver;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>probe</term>
      <listitem><para>
   Binds this driver to the spi device.  Drivers can verify
   that the device is actually present, and may need to configure
   characteristics (such as bits_per_word) which weren't needed for
   the initial configuration done during system setup.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>remove</term>
      <listitem><para>
   Unbinds this driver from the spi device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>shutdown</term>
      <listitem><para>
   Standard shutdown callback used during system state
   transitions such as powerdown/halt and kexec
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>suspend</term>
      <listitem><para>
   Standard suspend callback used during system state transitions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>resume</term>
      <listitem><para>
   Standard resume callback used during system state transitions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver</term>
      <listitem><para>
   SPI device drivers should initialize the name and owner
   field of this structure.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This represents the kind of device driver that uses SPI messages to
   interact with the hardware at the other end of a SPI link.  It's called
   a <quote>protocol</quote> driver because it works through messages rather than talking
   directly to SPI hardware (which is what the underlying SPI controller
   driver does to pass those messages).  These protocols are defined in the
   specification for the device(s) supported by the driver.
   </para><para>

   As a rule, those device protocols represent the lowest level interface
   supported by a driver, and it will support upper level interfaces too.
   Examples of such upper levels include frameworks like MTD, networking,
   MMC, RTC, filesystem character device nodes, and hardware monitoring.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-unregister-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_unregister_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_unregister_driver</refname>
 <refpurpose>
     reverse effect of spi_register_driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>spi_unregister_driver </function></funcdef>
   <paramdef>struct spi_driver * <parameter>sdrv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sdrv</parameter></term>
   <listitem>
    <para>
     the driver to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
</refentry>

<refentry id="API-struct-spi-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_master</refname>
 <refpurpose>
     interface to SPI master controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_master {
  struct class_device cdev;
  s16 bus_num;
  u16 num_chipselect;
  int (* setup) (struct spi_device *spi);
  int (* transfer) (struct spi_device *spi,struct spi_message *mesg);
  void (* cleanup) (struct spi_device *spi);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>cdev</term>
      <listitem><para>
   class interface to this driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus_num</term>
      <listitem><para>
   board-specific (and often SOC-specific) identifier for a
   given SPI controller.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_chipselect</term>
      <listitem><para>
   chipselects are used to distinguish individual
   SPI slaves, and are numbered from zero to num_chipselects.
   each slave has a chipselect signal, but it's common that not
   every chipselect is connected to a slave.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>setup</term>
      <listitem><para>
   updates the device mode and clocking records used by a
   device's SPI controller; protocol code may call this.  This
   must fail if an unrecognized or unsupported mode is requested.
   It's always safe to call this unless transfers are pending on
   the device whose settings are being modified.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transfer</term>
      <listitem><para>
   adds a message to the controller's transfer queue.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cleanup</term>
      <listitem><para>
   frees controller-specific state
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Each SPI master controller can communicate with one or more <parameter>spi_device</parameter>
   children.  These make a small bus, sharing MOSI, MISO and SCK signals
   but not chip select signals.  Each device may be configured to use a
   different clock rate, since those shared signals are ignored unless
   the chip is selected.
   </para><para>

   The driver for an SPI controller manages access to those devices through
   a queue of spi_message transactions, copying data between CPU memory and
   an SPI slave device.  For each such message it queues, it calls the
   message's completion function when the transaction completes.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-spi-transfer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_transfer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_transfer</refname>
 <refpurpose>
     a read/write buffer pair
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_transfer {
  const void * tx_buf;
  void * rx_buf;
  unsigned len;
  dma_addr_t tx_dma;
  dma_addr_t rx_dma;
  unsigned cs_change:1;
  u8 bits_per_word;
  u16 delay_usecs;
  u32 speed_hz;
  struct list_head transfer_list;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>tx_buf</term>
      <listitem><para>
   data to be written (dma-safe memory), or NULL
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_buf</term>
      <listitem><para>
   data to be read (dma-safe memory), or NULL
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>len</term>
      <listitem><para>
   size of rx and tx buffers (in bytes)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_dma</term>
      <listitem><para>
   DMA address of tx_buf, if <parameter>spi_message</parameter>.is_dma_mapped
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_dma</term>
      <listitem><para>
   DMA address of rx_buf, if <parameter>spi_message</parameter>.is_dma_mapped
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cs_change</term>
      <listitem><para>
   affects chipselect after this transfer completes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bits_per_word</term>
      <listitem><para>
   select a bits_per_word other then the device default
   for this transfer. If 0 the default (from <parameter>spi_device</parameter>) is used.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>delay_usecs</term>
      <listitem><para>
   microseconds to delay after this transfer before
   (optionally) changing the chipselect status, then starting
   the next transfer or completing this <parameter>spi_message</parameter>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>speed_hz</term>
      <listitem><para>
   Select a speed other then the device default for this
   transfer. If 0 the default (from <parameter>spi_device</parameter>) is used.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transfer_list</term>
      <listitem><para>
   transfers are sequenced through <parameter>spi_message</parameter>.transfers
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   SPI transfers always write the same number of bytes as they read.
   Protocol drivers should always provide <parameter>rx_buf</parameter> and/or <parameter>tx_buf</parameter>.
   In some cases, they may also want to provide DMA addresses for
   the data being transferred; that may reduce overhead, when the
   underlying driver uses dma.
   </para><para>

   If the transmit buffer is null, zeroes will be shifted out
   while filling <parameter>rx_buf</parameter>.  If the receive buffer is null, the data
   shifted in will be discarded.  Only <quote>len</quote> bytes shift out (or in).
   It's an error to try to shift out a partial word.  (For example, by
   shifting out three bytes with word size of sixteen or twenty bits;
   the former uses two bytes per word, the latter uses four bytes.)
   </para><para>

   In-memory data values are always in native CPU byte order, translated
   from the wire byte order (big-endian except with SPI_LSB_FIRST).  So
   for example when bits_per_word is sixteen, buffers are 2N bytes long
   (<parameter>len</parameter> = 2N) and hold N sixteen bit words in CPU byte order.
   </para><para>

   When the word size of the SPI transfer is not a power-of-two multiple
   of eight bits, those in-memory words include extra bits.  In-memory
   words are always seen by protocol drivers as right-justified, so the
   undefined (rx) or unused (tx) bits are always the most significant bits.
   </para><para>

   All SPI transfers start with the relevant chipselect active.  Normally
   it stays selected until after the last transfer in a message.  Drivers
   can affect the chipselect signal using cs_change.
   </para><para>

   (i) If the transfer isn't the last one in the message, this flag is
   used to make the chipselect briefly go inactive in the middle of the
   message.  Toggling chipselect in this way may be needed to terminate
   a chip command, letting a single spi_message perform all of group of
   chip transactions together.
   </para><para>

   (ii) When the transfer is the last one in the message, the chip may
   stay selected until the next transfer.  On multi-device SPI busses
   with nothing blocking messages going to other devices, this is just
   a performance hint; starting a message to another device deselects
   this one.  But in other cases, this can be used to ensure correctness.
   Some devices need protocol transactions to be built from a series of
   spi_message submissions, where the content of one message is determined
   by the results of previous messages and where the whole transaction
   ends when the chipselect goes intactive.
   </para><para>

   The code that submits an spi_message (and its spi_transfers)
   to the lower layers is responsible for managing its memory.
   Zero-initialize every field you don't set up explicitly, to
   insulate against future API updates.  After you submit a message
   and its transfers, ignore them until its completion callback.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-spi-message">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_message</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_message</refname>
 <refpurpose>
     one multi-segment SPI transaction
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_message {
  struct list_head transfers;
  struct spi_device * spi;
  unsigned is_dma_mapped:1;
  void (* complete) (void *context);
  void * context;
  unsigned actual_length;
  int status;
  struct list_head queue;
  void * state;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>transfers</term>
      <listitem><para>
   list of transfer segments in this transaction
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>spi</term>
      <listitem><para>
   SPI device to which the transaction is queued
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>is_dma_mapped</term>
      <listitem><para>
   if true, the caller provided both dma and cpu virtual
   addresses for each transfer buffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>complete</term>
      <listitem><para>
   called to report transaction completions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>context</term>
      <listitem><para>
   the argument to <function>complete</function> when it's called
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>actual_length</term>
      <listitem><para>
   the total number of bytes that were transferred in all
   successful segments
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>status</term>
      <listitem><para>
   zero for success, else negative errno
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>queue</term>
      <listitem><para>
   for use by whichever driver currently owns the message
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>state</term>
      <listitem><para>
   for use by whichever driver currently owns the message
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   A <parameter>spi_message</parameter> is used to execute an atomic sequence of data transfers,
   each represented by a struct spi_transfer.  The sequence is <quote>atomic</quote>
   in the sense that no other spi_message may use that SPI bus until that
   sequence completes.  On some systems, many such sequences can execute as
   as single programmed DMA transfer.  On all systems, these messages are
   queued, and might complete after transactions to other devices.  Messages
   sent to a given spi_device are alway executed in FIFO order.
   </para><para>

   The code that submits an spi_message (and its spi_transfers)
   to the lower layers is responsible for managing its memory.
   Zero-initialize every field you don't set up explicitly, to
   insulate against future API updates.  After you submit a message
   and its transfers, ignore them until its completion callback.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-setup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_setup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_setup</refname>
 <refpurpose>
     setup SPI mode and clock rate
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_setup </function></funcdef>
   <paramdef>struct spi_device * <parameter>spi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     the device whose settings are being modified
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep, and no requests are queued to the device
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   SPI protocol drivers may need to update the transfer mode if the
   device doesn't work with its default.  They may likewise need
   to update clock rates or word sizes from initial values.  This function
   changes those settings, and must be called from a context that can sleep.
   Except for SPI_CS_HIGH, which takes effect immediately, the changes take
   effect the next time the device is selected and data is transferred to
   or from it.  When this function returns, the spi device is deselected.
   </para><para>

   Note that this call will fail if the protocol driver specifies an option
   that the underlying controller or its driver does not support.  For
   example, not all hardware supports wire transfers using nine bit words,
   LSB-first wire encoding, or active-high chipselects.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-async">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_async</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_async</refname>
 <refpurpose>
     asynchronous SPI transfer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_async </function></funcdef>
   <paramdef>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>struct spi_message * <parameter>message</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>message</parameter></term>
   <listitem>
    <para>
     describes the data transfers, including completion callback
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   any (irqs may be blocked, etc)
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call may be used in_irq and other contexts which can't sleep,
   as well as from task contexts which can sleep.
   </para><para>

   The completion callback is invoked in a context which can't sleep.
   Before that invocation, the value of message-&gt;status is undefined.
   When the callback is issued, message-&gt;status holds either zero (to
   indicate complete success) or a negative error code.  After that
   callback returns, the driver which issued the transfer request may
   deallocate the associated memory; it's no longer in use by any SPI
   core or controller driver code.
   </para><para>

   Note that although all messages to a spi_device are handled in
   FIFO order, messages may go to different devices in other orders.
   Some device might be higher priority, or have various <quote>hard</quote> access
   time requirements, for example.
   </para><para>

   On detection of any fault during the transfer, processing of
   the entire message is aborted, and the device is deselected.
   Until returning from the associated message completion callback,
   no other spi_message queued to that device will be processed.
   (This rule applies equally to all the synchronous transfer calls,
   which are wrappers around this core asynchronous primitive.)
</para>
</refsect1>
</refentry>

<refentry id="API-spi-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_write</refname>
 <refpurpose>
     SPI synchronous write
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_write </function></funcdef>
   <paramdef>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>const u8 * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device to which data will be written
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     data buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     data buffer size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This writes the buffer and returns zero or a negative error code.
   Callable only from contexts that can sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_read</refname>
 <refpurpose>
     SPI synchronous read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_read </function></funcdef>
   <paramdef>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>u8 * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device from which data will be read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     data buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     data buffer size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This reads the buffer and returns zero or a negative error code.
   Callable only from contexts that can sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-w8r8">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_w8r8</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_w8r8</refname>
 <refpurpose>
     SPI synchronous 8 bit write followed by 8 bit read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>spi_w8r8 </function></funcdef>
   <paramdef>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>u8 <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     command to be written before data is read back
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns the (unsigned) eight bit number returned by the
   device, or else a negative error code.  Callable only from
   contexts that can sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-w8r16">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_w8r16</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_w8r16</refname>
 <refpurpose>
     SPI synchronous 8 bit write followed by 16 bit read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>spi_w8r16 </function></funcdef>
   <paramdef>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>u8 <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     command to be written before data is read back
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns the (unsigned) sixteen bit number returned by the
   device, or else a negative error code.  Callable only from
   contexts that can sleep.
   </para><para>

   The number is returned in wire-order, which is at least sometimes
   big-endian.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-spi-board-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct spi_board_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct spi_board_info</refname>
 <refpurpose>
     board-specific template for a SPI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct spi_board_info {
  char modalias[KOBJ_NAME_LEN];
  const void * platform_data;
  void * controller_data;
  int irq;
  u32 max_speed_hz;
  u16 bus_num;
  u16 chip_select;
  u8 mode;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>modalias[KOBJ_NAME_LEN]</term>
      <listitem><para>
   Initializes spi_device.modalias; identifies the driver.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>platform_data</term>
      <listitem><para>
   Initializes spi_device.platform_data; the particular
   data stored there is driver-specific.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>controller_data</term>
      <listitem><para>
   Initializes spi_device.controller_data; some
   controllers need hints about hardware setup, e.g. for DMA.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>irq</term>
      <listitem><para>
   Initializes spi_device.irq; depends on how the board is wired.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_speed_hz</term>
      <listitem><para>
   Initializes spi_device.max_speed_hz; based on limits
   from the chip datasheet and board-specific signal quality issues.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bus_num</term>
      <listitem><para>
   Identifies which spi_master parents the spi_device; unused
   by <function>spi_new_device</function>, and otherwise depends on board wiring.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>chip_select</term>
      <listitem><para>
   Initializes spi_device.chip_select; depends on how
   the board is wired.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode</term>
      <listitem><para>
   Initializes spi_device.mode; based on the chip datasheet, board
   wiring (some devices support both 3WIRE and standard modes), and
   possibly presence of an inverter in the chipselect path.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   When adding new SPI devices to the device tree, these structures serve
   as a partial device template.  They hold information which can't always
   be determined by drivers.  Information that <function>probe</function> can establish (such
   as the default transfer wordsize) is not included here.
   </para><para>

   These structures are used in two places.  Their primary role is to
   be stored in tables of board-specific device descriptors, which are
   declared early in board initialization and then used (much later) to
   populate a controller's device tree after the that controller's driver
   initializes.  A secondary (and atypical) role is as a parameter to
   <function>spi_new_device</function> call, which happens after those controller drivers
   are active in some dynamic board configuration models.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-register-board-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_register_board_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_register_board_info</refname>
 <refpurpose>
  register SPI devices for a given board
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>spi_register_board_info </function></funcdef>
   <paramdef>struct spi_board_info const * <parameter>info</parameter></paramdef>
   <paramdef>unsigned <parameter>n</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     array of chip descriptors
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n</parameter></term>
   <listitem>
    <para>
     how many descriptors are provided
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Board-specific early init code calls this (probably during arch_initcall)
   with segments of the SPI device table.  Any device nodes are created later,
   after the relevant parent SPI controller (bus_num) is defined.  We keep
   this table of devices forever, so that reloading a controller driver will
   not make Linux forget about these hard-wired devices.
   </para><para>

   Other code can also call this, e.g. a particular add-on board might provide
   SPI devices through its expansion connector, so code initializing that board
   would naturally declare its SPI devices.
   </para><para>

   The board info passed can safely be __initdata ... but be careful of
   any embedded pointers (platform_data, etc), they're copied as-is.
</para>
</refsect1>
</refentry>

<!-- drivers/spi/spi.c -->
<refentry id="API-spi-register-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_register_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_register_driver</refname>
 <refpurpose>
  register a SPI driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_register_driver </function></funcdef>
   <paramdef>struct spi_driver * <parameter>sdrv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sdrv</parameter></term>
   <listitem>
    <para>
     the driver to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
</refentry>

<refentry id="API-spi-new-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_new_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_new_device</refname>
 <refpurpose>
     instantiate one new SPI device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct spi_device * <function>spi_new_device </function></funcdef>
   <paramdef>struct spi_master * <parameter>master</parameter></paramdef>
   <paramdef>struct spi_board_info * <parameter>chip</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     Controller to which device is connected
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>chip</parameter></term>
   <listitem>
    <para>
     Describes the SPI device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   On typical mainboards, this is purely internal; and it's not needed
   after board init creates the hard-wired devices.  Some development
   platforms may not be able to use spi_register_board_info though, and
   this is exported so that for example a USB or parport based adapter
   driver could add devices (which it would learn about out-of-band).
   </para><para>

   Returns the new device, or NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-alloc-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_alloc_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_alloc_master</refname>
 <refpurpose>
     allocate SPI master controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct spi_master * <function>spi_alloc_master </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the controller, possibly using the platform_bus
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     how much zeroed driver-private data to allocate; the pointer to this
     memory is in the class_data field of the returned class_device,
     accessible with <function>spi_master_get_devdata</function>.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call is used only by SPI master controller drivers, which are the
   only ones directly touching chip registers.  It's how they allocate
   an spi_master structure, prior to calling <function>spi_register_master</function>.
   </para><para>

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

   The caller is responsible for assigning the bus number and initializing
   the master's methods before calling <function>spi_register_master</function>; and (after errors
   adding the device) calling <function>spi_master_put</function> to prevent a memory leak.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-register-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_register_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_register_master</refname>
 <refpurpose>
     register SPI master controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_register_master </function></funcdef>
   <paramdef>struct spi_master * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     initialized master, originally from <function>spi_alloc_master</function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   SPI master controllers connect to their drivers using some non-SPI bus,
   such as the platform bus.  The final stage of <function>probe</function> in that code
   includes calling <function>spi_register_master</function> to hook up to this SPI bus glue.
   </para><para>

   SPI controllers use board specific (often SOC specific) bus numbers,
   and board-specific addressing for SPI devices combines those numbers
   with chip select numbers.  Since SPI does not directly support dynamic
   device identification, boards need configuration tables telling which
   chip is at which address.
   </para><para>

   This must be called from context that can sleep.  It returns zero on
   success, else a negative error code (dropping the master's refcount).
   After a successful return, the caller is responsible for calling
   <function>spi_unregister_master</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-unregister-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_unregister_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_unregister_master</refname>
 <refpurpose>
     unregister SPI master controller
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>spi_unregister_master </function></funcdef>
   <paramdef>struct spi_master * <parameter>master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>master</parameter></term>
   <listitem>
    <para>
     the master being unregistered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call is used only by SPI master controller drivers, which are the
   only ones directly touching chip registers.
   </para><para>

   This must be called from context that can sleep.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-busnum-to-master">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_busnum_to_master</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_busnum_to_master</refname>
 <refpurpose>
     look up master associated with bus_num
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct spi_master * <function>spi_busnum_to_master </function></funcdef>
   <paramdef>u16 <parameter>bus_num</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bus_num</parameter></term>
   <listitem>
    <para>
     the master's bus number
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call may be used with devices that are registered after
   arch init time.  It returns a refcounted pointer to the relevant
   spi_master (which the caller must release), or NULL if there is
   no such master registered.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-sync">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_sync</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_sync</refname>
 <refpurpose>
     blocking/synchronous SPI data transfers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_sync </function></funcdef>
   <paramdef>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>struct spi_message * <parameter>message</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>message</parameter></term>
   <listitem>
    <para>
     describes the data transfers
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This call may only be used from a context that may sleep.  The sleep
   is non-interruptible, and has no timeout.  Low-overhead controller
   drivers may DMA directly into and out of the message buffers.
   </para><para>

   Note that the SPI device's chip select is active during the message,
   and then is normally disabled between messages.  Drivers for some
   frequently-used devices may want to minimize costs of selecting a chip,
   by leaving it selected in anticipation that the next message will go
   to the same chip.  (That may increase power usage.)
   </para><para>

   Also, the caller is guaranteeing that the memory associated with the
   message will not be freed before this call returns.
   </para><para>

   The return value is a negative error code if the message could not be
   submitted, else zero.  When the value is zero, then message-&gt;status is
   also defined;  it's the completion code for the transfer, either zero
   or a negative error code from the controller driver.
</para>
</refsect1>
</refentry>

<refentry id="API-spi-write-then-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>spi_write_then_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>spi_write_then_read</refname>
 <refpurpose>
     SPI synchronous write followed by read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>spi_write_then_read </function></funcdef>
   <paramdef>struct spi_device * <parameter>spi</parameter></paramdef>
   <paramdef>const u8 * <parameter>txbuf</parameter></paramdef>
   <paramdef>unsigned <parameter>n_tx</parameter></paramdef>
   <paramdef>u8 * <parameter>rxbuf</parameter></paramdef>
   <paramdef>unsigned <parameter>n_rx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>spi</parameter></term>
   <listitem>
    <para>
     device with which data will be exchanged
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>txbuf</parameter></term>
   <listitem>
    <para>
     data to be written (need not be dma-safe)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n_tx</parameter></term>
   <listitem>
    <para>
     size of txbuf, in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rxbuf</parameter></term>
   <listitem>
    <para>
     buffer into which data will be read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>n_rx</parameter></term>
   <listitem>
    <para>
     size of rxbuf, in bytes (need not be dma-safe)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This performs a half duplex MicroWire style transaction with the
   device, sending txbuf and then reading rxbuf.  The return value
   is zero for success, else a negative errno status code.
   This call may only be used from a context that may sleep.
   </para><para>

   Parameters to this routine are always copied using a small buffer;
   portable code should never use this for more than 32 bytes.
   Performance-sensitive or bulk transfer code should instead use
   spi_{async,sync}() calls with dma-safe buffers.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="i2c">
     <title>I<superscript>2</superscript>C and SMBus Subsystem</title>

     <para>
	I<superscript>2</superscript>C (or without fancy typography, "I2C")
	is an acronym for the "Inter-IC" bus, a simple bus protocol which is
	widely used where low data rate communications suffice.
	Since it's also a licensed trademark, some vendors use another
	name (such as "Two-Wire Interface", TWI) for the same bus.
	I2C only needs two signals (SCL for clock, SDA for data), conserving
	board real estate and minimizing signal quality issues.
	Most I2C devices use seven bit addresses, and bus speeds of up
	to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet
	found wide use.
	I2C is a multi-master bus; open drain signaling is used to
	arbitrate between masters, as well as to handshake and to
	synchronize clocks from slower clients.
     </para>

     <para>
	The Linux I2C programming interfaces support only the master
	side of bus interactions, not the slave side.
	The programming interface is structured around two kinds of driver,
	and two kinds of device.
	An I2C "Adapter Driver" abstracts the controller hardware; it binds
	to a physical device (perhaps a PCI device or platform_device) and
	exposes a <structname>struct i2c_adapter</structname> representing
	each I2C bus segment it manages.
	On each I2C bus segment will be I2C devices represented by a
	<structname>struct i2c_client</structname>.  Those devices will
	be bound to a <structname>struct i2c_driver</structname>,
	which should follow the standard Linux driver model.
	(At this writing, a legacy model is more widely used.)
	There are functions to perform various I2C protocol operations; at
	this writing all such functions are usable only from task context.
     </para>

     <para>
	The System Management Bus (SMBus) is a sibling protocol.  Most SMBus
	systems are also I2C conformant.  The electrical constraints are
	tighter for SMBus, and it standardizes particular protocol messages
	and idioms.  Controllers that support I2C can also support most
	SMBus operations, but SMBus controllers don't support all the protocol
	options that an I2C controller will.
	There are functions to perform various SMBus protocol operations,
	either using I2C primitives or by issuing SMBus commands to
	i2c_adapter devices which don't support those I2C operations.
     </para>

<!-- include/linux/i2c.h -->
<refentry id="API-struct-i2c-client">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct i2c_client</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct i2c_client</refname>
 <refpurpose>
  represent an I2C slave device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct i2c_client {
  unsigned short flags;
  unsigned short addr;
  char name[I2C_NAME_SIZE];
  struct i2c_adapter * adapter;
  struct i2c_driver * driver;
  int usage_count;
  struct device dev;
  int irq;
  char driver_name[KOBJ_NAME_LEN];
  struct list_head list;
  struct completion released;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>flags</term>
      <listitem><para>
I2C_CLIENT_TEN indicates the device uses a ten bit chip address;
I2C_CLIENT_PEC indicates it uses SMBus Packet Error Checking
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>addr</term>
      <listitem><para>
Address used on the I2C bus connected to the parent adapter.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name[I2C_NAME_SIZE]</term>
      <listitem><para>
Indicates the type of the device, usually a chip name that's
generic enough to hide second-sourcing and compatible revisions.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>adapter</term>
      <listitem><para>
manages the bus segment hosting this I2C device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver</term>
      <listitem><para>
device's driver, hence pointer to access routines
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>usage_count</term>
      <listitem><para>
counts current number of users of this client
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev</term>
      <listitem><para>
Driver model device node for the slave.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>irq</term>
      <listitem><para>
indicates the IRQ generated by this device (if any)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver_name[KOBJ_NAME_LEN]</term>
      <listitem><para>
Identifies new-style driver used with this device; also
used as the module name for hotplug/coldplug modprobe support.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>list</term>
      <listitem><para>
list of active/busy clients
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>released</term>
      <listitem><para>
used to synchronize client releases &amp; detaches and references
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   An i2c_client identifies a single device (i.e. chip) connected to an
   i2c bus. The behaviour exposed to Linux is defined by the driver
   managing the device.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-i2c-board-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct i2c_board_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct i2c_board_info</refname>
 <refpurpose>
     template for device creation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct i2c_board_info {
  char driver_name[KOBJ_NAME_LEN];
  char type[I2C_NAME_SIZE];
  unsigned short flags;
  unsigned short addr;
  void * platform_data;
  int irq;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>driver_name[KOBJ_NAME_LEN]</term>
      <listitem><para>
   identifies the driver to be bound to the device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type[I2C_NAME_SIZE]</term>
      <listitem><para>
   optional chip type information, to initialize i2c_client.name
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
   to initialize i2c_client.flags
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>addr</term>
      <listitem><para>
   stored in i2c_client.addr
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>platform_data</term>
      <listitem><para>
   stored in i2c_client.dev.platform_data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>irq</term>
      <listitem><para>
   stored in i2c_client.irq
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   I2C doesn't actually support hardware probing, although controllers and
   devices may be able to use I2C_SMBUS_QUICK to tell whether or not there's
   a device at a given address.  Drivers commonly need more information than
   that, such as chip type, configuration, associated IRQ, and so on.
   </para><para>

   i2c_board_info is used to build tables of information listing I2C devices
   that are present.  This information is used to grow the driver model tree
   for <quote>new style</quote> I2C drivers.  For mainboards this is done statically using
   <function>i2c_register_board_info</function>; bus numbers identify adapters that aren't
   yet available.  For add-on boards, <function>i2c_new_device</function> does this dynamically
   with the adapter already known.
</para>
</refsect1>
</refentry>

<refentry id="API-I2C-BOARD-INFO">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>I2C_BOARD_INFO</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>I2C_BOARD_INFO</refname>
 <refpurpose>
     macro used to list an i2c device and its driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>I2C_BOARD_INFO </function></funcdef>
   <paramdef> <parameter>driver</parameter></paramdef>
   <paramdef> <parameter>dev_addr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     identifies the driver to use with the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev_addr</parameter></term>
   <listitem>
    <para>
     the device's address on the bus.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This macro initializes essential fields of a struct i2c_board_info,
   declaring what has been provided on a particular board.  Optional
   fields (such as the chip type, its associated irq, or device-specific
   platform_data) are provided using conventional syntax.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-register-board-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_register_board_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_register_board_info</refname>
 <refpurpose>
  statically declare I2C devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int __init <function>i2c_register_board_info </function></funcdef>
   <paramdef>int <parameter>busnum</parameter></paramdef>
   <paramdef>struct i2c_board_info const * <parameter>info</parameter></paramdef>
   <paramdef>unsigned <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>busnum</parameter></term>
   <listitem>
    <para>
     identifies the bus to which these devices belong
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     vector of i2c device descriptors
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     how many descriptors in the vector; may be zero to reserve
     the specified bus number.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Systems using the Linux I2C driver stack can declare tables of board info
   while they initialize.  This should be done in board-specific init code
   near <function>arch_initcall</function> time, or equivalent, before any I2C adapter driver is
   registered.  For example, mainboard init code could define several devices,
   as could the init code for each daughtercard in a board stack.
   </para><para>

   The I2C devices will be created later, after the adapter for the relevant
   bus has been registered.  After that moment, standard driver model tools
   are used to bind <quote>new style</quote> I2C drivers to the devices.  The bus number
   for any device declared using this routine is not available for dynamic
   allocation.
   </para><para>

   The board info passed can safely be __initdata, but be careful of embedded
   pointers (for platform_data, functions, etc) since that won't be copied.
</para>
</refsect1>
</refentry>

<!-- drivers/i2c/i2c-core.c -->
<refentry id="API-i2c-new-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_new_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_new_device</refname>
 <refpurpose>
  instantiate an i2c device for use with a new style driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i2c_client * <function>i2c_new_device </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adap</parameter></paramdef>
   <paramdef>struct i2c_board_info const * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adap</parameter></term>
   <listitem>
    <para>
     the adapter managing the device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     describes one I2C device; bus_num is ignored
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Create a device to work with a new style i2c driver, where binding is
   handled through driver model <function>probe</function>/<function>remove</function> methods.  This call is not
   appropriate for use by mainboad initialization logic, which usually runs
   during an <function>arch_initcall</function> long before any i2c_adapter could exist.
   </para><para>

   This returns the new i2c client, which may be saved for later use with
   <function>i2c_unregister_device</function>; or NULL to indicate an error.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-unregister-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_unregister_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_unregister_device</refname>
 <refpurpose>
     reverse effect of <function>i2c_new_device</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2c_unregister_device </function></funcdef>
   <paramdef>struct i2c_client * <parameter>client</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     value returned from <function>i2c_new_device</function>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-add-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_add_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_add_adapter</refname>
 <refpurpose>
     declare i2c adapter, use dynamic bus number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2c_add_adapter </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adapter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adapter</parameter></term>
   <listitem>
    <para>
     the adapter to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is used to declare an I2C adapter when its bus number
   doesn't matter.  Examples: for I2C adapters dynamically added by
   USB links or PCI plugin cards.
   </para><para>

   When this returns zero, a new bus number was allocated and stored
   in adap-&gt;nr, and the specified adapter became available for clients.
   Otherwise, a negative errno value is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-add-numbered-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_add_numbered_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_add_numbered_adapter</refname>
 <refpurpose>
     declare i2c adapter, use static bus number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2c_add_numbered_adapter </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adap</parameter></term>
   <listitem>
    <para>
     the adapter to register (with adap-&gt;nr initialized)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine is used to declare an I2C adapter when its bus number
   matters.  Example: for I2C adapters from system-on-chip CPUs, or
   otherwise built in to the system's mainboard, and where i2c_board_info
   is used to properly configure I2C devices.
   </para><para>

   If no devices have pre-been declared for this bus, then be sure to
   register the adapter before any dynamically allocated ones.  Otherwise
   the required bus ID may not be available.
   </para><para>

   When this returns zero, the specified adapter became available for
   clients using the bus number provided in adap-&gt;nr.  Also, the table
   of I2C devices pre-declared using <function>i2c_register_board_info</function> is scanned,
   and the appropriate driver model device nodes are created.  Otherwise, a
   negative errno value is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-del-adapter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_del_adapter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_del_adapter</refname>
 <refpurpose>
     unregister I2C adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i2c_del_adapter </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adap</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adap</parameter></term>
   <listitem>
    <para>
     the adapter being unregistered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This unregisters an I2C adapter which was previously registered
   by <parameter>i2c_add_adapter</parameter> or <parameter>i2c_add_numbered_adapter</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-i2c-del-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i2c_del_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i2c_del_driver</refname>
 <refpurpose>
     unregister I2C driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i2c_del_driver </function></funcdef>
   <paramdef>struct i2c_driver * <parameter>driver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     the driver being unregistered
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Context</title>
<para>
   can sleep
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="splice">
      <title>splice API</title>
  <para>
	splice is a method for moving blocks of data around inside the
	kernel, without continually transferring them between the kernel
	and user space.
  </para>
<refentry id="API-splice-to-pipe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>splice_to_pipe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>splice_to_pipe</refname>
 <refpurpose>
  fill passed data into a pipe
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>splice_to_pipe </function></funcdef>
   <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
   <paramdef>struct splice_pipe_desc * <parameter>spd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     pipe to fill
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>spd</parameter></term>
   <listitem>
    <para>
     data to fill
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <parameter>spd</parameter> contains a map of pages and len/offset tuples, along with
   the struct pipe_buf_operations associated with these pages. This
   function will link that data to the pipe.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-file-splice-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_file_splice_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_file_splice_read</refname>
 <refpurpose>
     splice data from file to a pipe
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>generic_file_splice_read </function></funcdef>
   <paramdef>struct file * <parameter>in</parameter></paramdef>
   <paramdef>loff_t * <parameter>ppos</parameter></paramdef>
   <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>in</parameter></term>
   <listitem>
    <para>
     file to splice from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ppos</parameter></term>
   <listitem>
    <para>
     position in <parameter>in</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     pipe to splice to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes to splice
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     splice modifier flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Will read pages from given file and fill them into a pipe. Can be
   used as long as the address_space operations for the source implements
   a <function>readpage</function> hook.
</para>
</refsect1>
</refentry>

<refentry id="API---splice-from-pipe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__splice_from_pipe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__splice_from_pipe</refname>
 <refpurpose>
     splice data from a pipe to given actor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>__splice_from_pipe </function></funcdef>
   <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
   <paramdef>struct splice_desc * <parameter>sd</parameter></paramdef>
   <paramdef>splice_actor * <parameter>actor</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     pipe to splice from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sd</parameter></term>
   <listitem>
    <para>
     information to <parameter>actor</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>actor</parameter></term>
   <listitem>
    <para>
     handler that splices the data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function does little more than loop over the pipe and call
   <parameter>actor</parameter> to do the actual moving of a single struct pipe_buffer to
   the desired destination. See pipe_to_file, pipe_to_sendpage, or
   pipe_to_user.
</para>
</refsect1>
</refentry>

<refentry id="API-splice-from-pipe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>splice_from_pipe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>splice_from_pipe</refname>
 <refpurpose>
     splice data from a pipe to a file
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>splice_from_pipe </function></funcdef>
   <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
   <paramdef>struct file * <parameter>out</parameter></paramdef>
   <paramdef>loff_t * <parameter>ppos</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
   <paramdef>splice_actor * <parameter>actor</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     pipe to splice from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>out</parameter></term>
   <listitem>
    <para>
     file to splice to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ppos</parameter></term>
   <listitem>
    <para>
     position in <parameter>out</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     how many bytes to splice
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     splice modifier flags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>actor</parameter></term>
   <listitem>
    <para>
     handler that splices the data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   See __splice_from_pipe. This function locks the input and output inodes,
   otherwise it's identical to <function>__splice_from_pipe</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-file-splice-write-nolock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_file_splice_write_nolock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_file_splice_write_nolock</refname>
 <refpurpose>
     generic_file_splice_write without mutexes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>generic_file_splice_write_nolock </function></funcdef>
   <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
   <paramdef>struct file * <parameter>out</parameter></paramdef>
   <paramdef>loff_t * <parameter>ppos</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     pipe info
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>out</parameter></term>
   <listitem>
    <para>
     file to write to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ppos</parameter></term>
   <listitem>
    <para>
     position in <parameter>out</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes to splice
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     splice modifier flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Will either move or copy pages (determined by <parameter>flags</parameter> options) from
   the given pipe inode to the given file. The caller is responsible
   for acquiring i_mutex on both inodes.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-file-splice-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_file_splice_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_file_splice_write</refname>
 <refpurpose>
     splice data from a pipe to a file
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>generic_file_splice_write </function></funcdef>
   <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
   <paramdef>struct file * <parameter>out</parameter></paramdef>
   <paramdef>loff_t * <parameter>ppos</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     pipe info
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>out</parameter></term>
   <listitem>
    <para>
     file to write to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ppos</parameter></term>
   <listitem>
    <para>
     position in <parameter>out</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes to splice
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     splice modifier flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Will either move or copy pages (determined by <parameter>flags</parameter> options) from
   the given pipe inode to the given file.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-splice-sendpage">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_splice_sendpage</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_splice_sendpage</refname>
 <refpurpose>
     splice data from a pipe to a socket
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>generic_splice_sendpage </function></funcdef>
   <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
   <paramdef>struct file * <parameter>out</parameter></paramdef>
   <paramdef>loff_t * <parameter>ppos</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     pipe to splice from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>out</parameter></term>
   <listitem>
    <para>
     socket to write to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ppos</parameter></term>
   <listitem>
    <para>
     position in <parameter>out</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes to splice
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     splice modifier flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Will send <parameter>len</parameter> bytes from the pipe to a network socket. No data copying
   is involved.
</para>
</refsect1>
</refentry>

<refentry id="API-splice-direct-to-actor">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>splice_direct_to_actor</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>splice_direct_to_actor</refname>
 <refpurpose>
     splices data directly between two non-pipes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>splice_direct_to_actor </function></funcdef>
   <paramdef>struct file * <parameter>in</parameter></paramdef>
   <paramdef>struct splice_desc * <parameter>sd</parameter></paramdef>
   <paramdef>splice_direct_actor * <parameter>actor</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>in</parameter></term>
   <listitem>
    <para>
     file to splice from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sd</parameter></term>
   <listitem>
    <para>
     actor information on where to splice to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>actor</parameter></term>
   <listitem>
    <para>
     handles the data splicing
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a special case helper to splice directly between two
   points, without requiring an explicit pipe. Internally an allocated
   pipe is cached in the process, and reused during the lifetime of
   that process.
</para>
</refsect1>
</refentry>

<refentry id="API-do-splice-direct">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>do_splice_direct</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>do_splice_direct</refname>
 <refpurpose>
     splices data directly between two files
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>do_splice_direct </function></funcdef>
   <paramdef>struct file * <parameter>in</parameter></paramdef>
   <paramdef>loff_t * <parameter>ppos</parameter></paramdef>
   <paramdef>struct file * <parameter>out</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>in</parameter></term>
   <listitem>
    <para>
     file to splice from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ppos</parameter></term>
   <listitem>
    <para>
     input file offset
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>out</parameter></term>
   <listitem>
    <para>
     file to splice to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     number of bytes to splice
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     splice modifier flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   For use by <function>do_sendfile</function>. splice can easily emulate sendfile, but
   doing it in the application would incur an extra system call
   (splice in + splice out, as compared to just <function>sendfile</function>). So this helper
   can splice directly through a process-private pipe.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="pipes">
      <title>pipes API</title>
  <para>
	Pipe interfaces are all for in-kernel (builtin image) use.
	They are not exported for use by modules.
  </para>
<!-- include/linux/pipe_fs_i.h -->
<refentry id="API-struct-pipe-buffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct pipe_buffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct pipe_buffer</refname>
 <refpurpose>
  a linux kernel pipe buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct pipe_buffer {
  struct page * page;
  unsigned int offset;
  unsigned int len;
  const struct pipe_buf_operations * ops;
  unsigned int flags;
  unsigned long private;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>page</term>
      <listitem><para>
the page containing the data for the pipe buffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>offset</term>
      <listitem><para>
offset of data inside the <parameter>page</parameter>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>len</term>
      <listitem><para>
length of data inside the <parameter>page</parameter>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ops</term>
      <listitem><para>
operations associated with this buffer. See <parameter>pipe_buf_operations</parameter>.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
pipe buffer flags. See above.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>private</term>
      <listitem><para>
private data owned by the ops.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-pipe-inode-info">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct pipe_inode_info</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct pipe_inode_info</refname>
 <refpurpose>
     a linux kernel pipe
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct pipe_inode_info {
  wait_queue_head_t wait;
  unsigned int nrbufs;
  unsigned int curbuf;
  struct page * tmp_page;
  unsigned int readers;
  unsigned int writers;
  unsigned int waiting_writers;
  unsigned int r_counter;
  unsigned int w_counter;
  struct fasync_struct * fasync_readers;
  struct fasync_struct * fasync_writers;
  struct inode * inode;
  struct pipe_buffer bufs[PIPE_BUFFERS];
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>wait</term>
      <listitem><para>
   reader/writer wait point in case of empty/full pipe
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>nrbufs</term>
      <listitem><para>
   the number of non-empty pipe buffers in this pipe
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>curbuf</term>
      <listitem><para>
   the current pipe buffer entry
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tmp_page</term>
      <listitem><para>
   cached released page
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>readers</term>
      <listitem><para>
   number of current readers of this pipe
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>writers</term>
      <listitem><para>
   number of current writers of this pipe
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>waiting_writers</term>
      <listitem><para>
   number of writers blocked waiting for room
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>r_counter</term>
      <listitem><para>
   reader counter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>w_counter</term>
      <listitem><para>
   writer counter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fasync_readers</term>
      <listitem><para>
   reader side fasync
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fasync_writers</term>
      <listitem><para>
   writer side fasync
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>inode</term>
      <listitem><para>
   inode this pipe is attached to
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bufs[PIPE_BUFFERS]</term>
      <listitem><para>
   the circular array of pipe buffers
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-generic-pipe-buf-map">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_pipe_buf_map</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_pipe_buf_map</refname>
 <refpurpose>
  virtually map a pipe buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>generic_pipe_buf_map </function></funcdef>
   <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
   <paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef>
   <paramdef>int <parameter>atomic</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     the pipe that the buffer belongs to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     the buffer that should be mapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>atomic</parameter></term>
   <listitem>
    <para>
     whether to use an atomic map
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function returns a kernel virtual address mapping for the
   passed in <parameter>pipe_buffer</parameter>. If <parameter>atomic</parameter> is set, an atomic map is provided
   and the caller has to be careful not to fault before calling
   the unmap function.
   </para><para>

   Note that this function occupies KM_USER0 if <parameter>atomic</parameter> != 0.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-pipe-buf-unmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_pipe_buf_unmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_pipe_buf_unmap</refname>
 <refpurpose>
     unmap a previously mapped pipe buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>generic_pipe_buf_unmap </function></funcdef>
   <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
   <paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef>
   <paramdef>void * <parameter>map_data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     the pipe that the buffer belongs to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     the buffer that should be unmapped
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>map_data</parameter></term>
   <listitem>
    <para>
     the data that the mapping function returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function undoes the mapping that -&gt;<function>map</function> provided.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-pipe-buf-steal">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_pipe_buf_steal</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_pipe_buf_steal</refname>
 <refpurpose>
     attempt to take ownership of a <parameter>pipe_buffer</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>generic_pipe_buf_steal </function></funcdef>
   <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
   <paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     the pipe that the buffer belongs to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     the buffer to attempt to steal
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function attempts to steal the <parameter>struct</parameter> page attached to
   <parameter>buf</parameter>. If successful, this function returns 0 and returns with
   the page locked. The caller may then reuse the page for whatever
   he wishes, the typical use is insertion into a different file
   page cache.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-pipe-buf-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_pipe_buf_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_pipe_buf_get</refname>
 <refpurpose>
     get a reference to a <parameter>struct</parameter> pipe_buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>generic_pipe_buf_get </function></funcdef>
   <paramdef>struct pipe_inode_info * <parameter>pipe</parameter></paramdef>
   <paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     the pipe that the buffer belongs to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     the buffer to get a reference to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function grabs an extra reference to <parameter>buf</parameter>. It's used in
   in the <function>tee</function> system call, when we duplicate the buffers in one
   pipe into another.
</para>
</refsect1>
</refentry>

<refentry id="API-generic-pipe-buf-confirm">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>August 2007</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>generic_pipe_buf_confirm</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">2.6.23-rc3-git3</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>generic_pipe_buf_confirm</refname>
 <refpurpose>
     verify contents of the pipe buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>generic_pipe_buf_confirm </function></funcdef>
   <paramdef>struct pipe_inode_info * <parameter>info</parameter></paramdef>
   <paramdef>struct pipe_buffer * <parameter>buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     the pipe that the buffer belongs to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     the buffer to confirm
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function does nothing, because the generic pipe code uses
   pages that are always good when inserted into the pipe.
</para>
</refsect1>
</refentry>

  </chapter>

</book>
