Merge branch 'overlayfs-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mszeredi/vfs

Pull overlayfs updates from Miklos Szeredi:
 "This update contains:

   - try to clone on copy-up

   - allow renaming a directory

   - split source into managable chunks

   - misc cleanups and fixes

  It does not contain the read-only fd data inconsistency fix, which Al
  didn't like. I'll leave that to the next year..."

* 'overlayfs-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mszeredi/vfs: (36 commits)
  ovl: fix reStructuredText syntax errors in documentation
  ovl: fix return value of ovl_fill_super
  ovl: clean up kstat usage
  ovl: fold ovl_copy_up_truncate() into ovl_copy_up()
  ovl: create directories inside merged parent opaque
  ovl: opaque cleanup
  ovl: show redirect_dir mount option
  ovl: allow setting max size of redirect
  ovl: allow redirect_dir to default to "on"
  ovl: check for emptiness of redirect dir
  ovl: redirect on rename-dir
  ovl: lookup redirects
  ovl: consolidate lookup for underlying layers
  ovl: fix nested overlayfs mount
  ovl: check namelen
  ovl: split super.c
  ovl: use d_is_dir()
  ovl: simplify lookup
  ovl: check lower existence of rename target
  ovl: rename: simplify handling of lower/merged directory
  ...
diff --git a/CREDITS b/CREDITS
index d7ebdfb..10a9eee 100644
--- a/CREDITS
+++ b/CREDITS
@@ -2775,6 +2775,10 @@
 S: Valladolid 47009
 S: Spain
 
+N: Peter Oruba
+D: AMD Microcode loader driver
+S: Germany
+
 N: Jens Osterkamp
 E: jens@de.ibm.com
 D: Maintainer of Spidernet network driver for Cell
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3acc4f1..c8a8eb1 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -14,13 +14,8 @@
 	- this file.
 ABI/
 	- info on kernel <-> userspace ABI and relative interface stability.
-
-BUG-HUNTING
-	- brute force method of doing binary search of patches to find bug.
-Changes
-	- list of changes that break older software packages.
 CodingStyle
-	- how the maintainers expect the C code in the kernel to look.
+	- nothing here, just a pointer to process/coding-style.rst.
 DMA-API.txt
 	- DMA API, pci_ API & extensions for non-consistent memory machines.
 DMA-API-HOWTO.txt
@@ -33,8 +28,6 @@
 	- directory with DocBook templates etc. for kernel documentation.
 EDID/
 	- directory with info on customizing EDID for broken gfx/displays.
-HOWTO
-	- the process and procedures of how to do Linux kernel development.
 IPMI.txt
 	- info on Linux Intelligent Platform Management Interface (IPMI) Driver.
 IRQ-affinity.txt
@@ -46,62 +39,43 @@
 Intel-IOMMU.txt
 	- basic info on the Intel IOMMU virtualization support.
 Makefile
-	- This file does nothing. Removing it breaks make htmldocs and
-	  make distclean.
-ManagementStyle
-	- how to (attempt to) manage kernel hackers.
+	- It's not of interest for those who aren't touching the build system.
+Makefile.sphinx
+	- It's not of interest for those who aren't touching the build system.
+PCI/
+	- info related to PCI drivers.
 RCU/
 	- directory with info on RCU (read-copy update).
 SAK.txt
 	- info on Secure Attention Keys.
 SM501.txt
 	- Silicon Motion SM501 multimedia companion chip
-SecurityBugs
-	- procedure for reporting security bugs found in the kernel.
-SubmitChecklist
-	- Linux kernel patch submission checklist.
-SubmittingDrivers
-	- procedure to get a new driver source included into the kernel tree.
 SubmittingPatches
-	- procedure to get a source patch included into the kernel tree.
-VGA-softcursor.txt
-	- how to change your VGA cursor from a blinking underscore.
+	- nothing here, just a pointer to process/coding-style.rst.
 accounting/
 	- documentation on accounting and taskstats.
 acpi/
 	- info on ACPI-specific hooks in the kernel.
+admin-guide/
+	- info related to Linux users and system admins.
 aoe/
 	- description of AoE (ATA over Ethernet) along with config examples.
-applying-patches.txt
-	- description of various trees and how to apply their patches.
 arm/
 	- directory with info about Linux on the ARM architecture.
 arm64/
 	- directory with info about Linux on the 64 bit ARM architecture.
-assoc_array.txt
-	- generic associative array intro.
-atomic_ops.txt
-	- semantics and behavior of atomic and bitmask operations.
 auxdisplay/
 	- misc. LCD driver documentation (cfag12864b, ks0108).
 backlight/
 	- directory with info on controlling backlights in flat panel displays
-bad_memory.txt
-	- how to use kernel parameters to exclude bad RAM regions.
-basic_profiling.txt
-	- basic instructions for those who wants to profile Linux kernel.
 bcache.txt
 	- Block-layer cache on fast SSDs to improve slow (raid) I/O performance.
-binfmt_misc.txt
-	- info on the kernel support for extra binary formats.
 blackfin/
 	- directory with documentation for the Blackfin arch.
 block/
 	- info on the Block I/O (BIO) layer.
 blockdev/
 	- info on block devices & drivers
-braille-console.txt
-	- info on how to use serial devices for Braille support.
 bt8xxgpio.txt
 	- info on how to modify a bt8xx video card for GPIO usage.
 btmrvl.txt
@@ -114,18 +88,24 @@
 	- describes the cache/TLB flushing interfaces Linux uses.
 cdrom/
 	- directory with information on the CD-ROM drivers that Linux has.
-cgroups/
-	- cgroups features, including cpusets and memory controller.
+cgroup-v1/
+	- cgroups v1 features, including cpusets and memory controller.
+cgroup-v2.txt
+	- cgroups v2 features, including cpusets and memory controller.
 circular-buffers.txt
 	- how to make use of the existing circular buffer infrastructure
 clk.txt
 	- info on the common clock framework
-coccinelle.txt
-	- info on how to get and use the Coccinelle code checking tool.
+cma/
+	- Continuous Memory Area (CMA) debugfs interface.
+conf.py
+	- It's not of interest for those who aren't touching the build system.
 connector/
 	- docs on the netlink based userspace<->kernel space communication mod.
 console/
 	- documentation on Linux console drivers.
+core-api/
+	- documentation on kernel core components.
 cpu-freq/
 	- info on CPU frequency and voltage scaling.
 cpu-hotplug.txt
@@ -150,42 +130,42 @@
 	- how to use firewire like a hardware debugger memory reader.
 dell_rbu.txt
 	- document demonstrating the use of the Dell Remote BIOS Update driver.
-development-process/
-	- how to work with the mainline kernel development process.
+dev-tools/
+	- directory with info on development tools for the kernel.
 device-mapper/
 	- directory with info on Device Mapper.
-devices.txt
-	- plain ASCII listing of all the nodes in /dev/ with major minor #'s.
+dmaengine/
+	- the DMA engine and controller API guides.
 devicetree/
 	- directory with info on device tree files used by OF/PowerPC/ARM
 digsig.txt
 	-info on the Digital Signature Verification API
 dma-buf-sharing.txt
 	- the DMA Buffer Sharing API Guide
+docutils.conf
+	- nothing here. Just a configuration file for docutils.
 dontdiff
 	- file containing a list of files that should never be diff'ed.
+driver-api/
+	- the Linux driver implementer's API guide.
 driver-model/
 	- directory with info about Linux driver model.
-dvb/
-	- info on Linux Digital Video Broadcast (DVB) subsystem.
-dynamic-debug-howto.txt
-	- how to use the dynamic debug (dyndbg) feature.
 early-userspace/
 	- info about initramfs, klibc, and userspace early during boot.
-edac.txt
-	- information on EDAC - Error Detection And Correction
 efi-stub.txt
 	- How to use the EFI boot stub to bypass GRUB or elilo on EFI systems.
 eisa.txt
 	- info on EISA bus support.
-email-clients.txt
-	- info on how to use e-mail to send un-mangled (git) patches.
 extcon/
 	- directory with porting guide for Android kernel switch driver.
+isa.txt
+	- info on EISA bus support.
 fault-injection/
 	- dir with docs about the fault injection capabilities infrastructure.
 fb/
 	- directory with info on the frame buffer graphics abstraction layer.
+features/
+	- status of feature implementation on different architectures.
 filesystems/
 	- info on the vfs and the various filesystems that Linux supports.
 firmware_class/
@@ -194,20 +174,22 @@
 	- how to make use of flexible sized arrays in linux
 fmc/
 	- information about the FMC bus abstraction
+fpga/
+	- FPGA Manager Core.
 frv/
 	- Fujitsu FR-V Linux documentation.
 futex-requeue-pi.txt
 	- info on requeueing of tasks from a non-PI futex to a PI futex
-gcov.txt
-	- use of GCC's coverage testing tool "gcov" with the Linux kernel
+gcc-plugins.txt
+	- GCC plugin infrastructure.
 gpio/
 	- gpio related documentation
+gpu/
+	- directory with information on GPU driver developer's guide.
 hid/
 	- directory with information on human interface devices
 highuid.txt
 	- notes on the change from 16 bit to 32 bit user/group IDs.
-hsi.txt
-	- HSI subsystem overview.
 hwspinlock.txt
 	- hardware spinlock provides hardware assistance for synchronization
 timers/
@@ -218,18 +200,18 @@
 	- directory with docs on various hardware monitoring drivers.
 i2c/
 	- directory with info about the I2C bus/protocol (2 wire, kHz speed).
-i2o/
-	- directory with info about the Linux I2O subsystem.
 x86/i386/
 	- directory with info about Linux on Intel 32 bit architecture.
 ia64/
 	- directory with info about Linux on Intel 64 bit architecture.
+ide/
+	- Information regarding the Enhanced IDE drive.
+iio/
+	- info on industrial IIO configfs support.
+index.rst
+	- main index for the documentation at ReST format.
 infiniband/
 	- directory with documents concerning Linux InfiniBand support.
-init.txt
-	- what to do when the kernel can't find the 1st process to run.
-initrd.txt
-	- how to use the RAM disk as an initial/temporary root filesystem.
 input/
 	- info on Linux input device support.
 intel_txt.txt
@@ -248,28 +230,16 @@
 	- info on Linux ISA Plug & Play support.
 isdn/
 	- directory with info on the Linux ISDN support, and supported cards.
-java.txt
-	- info on the in-kernel binary support for Java(tm).
-ja_JP/
-	- directory with Japanese translations of various documents
 kbuild/
 	- directory with info about the kernel build process.
+kernel-doc-nano-HOWTO.txt
+	- outdated info about kernel-doc documentation.
 kdump/
 	- directory with mini HowTo on getting the crash dump code to work.
-kernel-docs.txt
-	- listing of various WWW + books that document kernel internals.
-kernel-documentation.rst
+doc-guide/
 	- how to write and format reStructuredText kernel documentation
-kernel-parameters.txt
-	- summary listing of command line / boot prompt args for the kernel.
 kernel-per-CPU-kthreads.txt
 	- List of all per-CPU kthreads and how they introduce jitter.
-kmemcheck.txt
-	- info on dynamic checker that detects uses of uninitialized memory.
-kmemleak.txt
-	- info on how to make use of the kernel memory leak detection system
-ko_KR/
-	- directory with Korean translations of various documents
 kobject.txt
 	- info of the kobject infrastructure of the Linux kernel.
 kprobes.txt
@@ -284,8 +254,8 @@
 	- a brief description of LDM (Windows Dynamic Disks).
 leds/
 	- directory with info about LED handling under Linux.
-local_ops.txt
-	- semantics and behavior of local atomic operations.
+livepatch/
+	- info on kernel live patching.
 locking/
 	- directory with info about kernel locking primitives
 lockup-watchdogs.txt
@@ -298,22 +268,24 @@
 	- kernel LZO decompressor input formats
 m68k/
 	- directory with info about Linux on Motorola 68k architecture.
-magic-number.txt
-	- list of magic numbers used to mark/protect kernel data structures.
 mailbox.txt
 	- How to write drivers for the common mailbox framework (IPC).
-md.txt
-	- info on boot arguments for the multiple devices driver.
-media-framework.txt
-	- info on media framework, its data structures, functions and usage.
+md-cluster.txt
+	- info on shared-device RAID MD cluster.
+media/
+	- info on media drivers: uAPI, kAPI and driver documentation.
 memory-barriers.txt
 	- info on Linux kernel memory barriers.
 memory-devices/
 	- directory with info on parts like the Texas Instruments EMIF driver
 memory-hotplug.txt
 	- Hotpluggable memory support, how to use and current status.
+men-chameleon-bus.txt
+	- info on MEN chameleon bus.
 metag/
 	- directory with info about Linux on Meta architecture.
+mic/
+	- Intel Many Integrated Core (MIC) architecture device driver.
 mips/
 	- directory with info about Linux on MIPS architecture.
 misc-devices/
@@ -322,12 +294,8 @@
 	- directory with info about the MMC subsystem
 mn10300/
 	- directory with info about the mn10300 architecture port
-module-signing.txt
-	- Kernel module signing for increased security when loading modules.
 mtd/
 	- directory with info about memory technology devices (flash)
-mono.txt
-	- how to execute Mono-based .NET binaries with the help of BINFMT_MISC.
 namespaces/
 	- directory with various information about namespaces
 netlabel/
@@ -336,30 +304,42 @@
 	- directory with info on various aspects of networking with Linux.
 nfc/
 	- directory relating info about Near Field Communications support.
+nios2/
+	- Linux on the Nios II architecture.
 nommu-mmap.txt
 	- documentation about no-mmu memory mapping support.
 numastat.txt
 	- info on how to read Numa policy hit/miss statistics in sysfs.
-oops-tracing.txt
-	- how to decode those nasty internal kernel error dump messages.
+ntb.txt
+	- info on Non-Transparent Bridge (NTB) drivers.
+nvdimm/
+	- info on non-volatile devices.
+nvmem/
+	- info on non volatile memory framework.
+output/
+	- default directory where html/LaTeX/pdf files will be written.
 padata.txt
 	- An introduction to the "padata" parallel execution API
 parisc/
 	- directory with info on using Linux on PA-RISC architecture.
-parport.txt
-	- how to use the parallel-port driver.
 parport-lowlevel.txt
 	- description and usage of the low level parallel port functions.
 pcmcia/
 	- info on the Linux PCMCIA driver.
 percpu-rw-semaphore.txt
 	- RCU based read-write semaphore optimized for locking for reading
+perf/
+	- info about the APM X-Gene SoC Performance Monitoring Unit (PMU).
+phy/
+	- ino on Samsung USB 2.0 PHY adaptation layer.
 phy.txt
 	- Description of the generic PHY framework.
 pi-futex.txt
 	- documentation on lightweight priority inheritance futexes.
 pinctrl.txt
 	- info on pinctrl subsystem and the PINMUX/PINCONF and drivers
+platform/
+	- List of supported hardware by compal and Dell laptop.
 pnp.txt
 	- Linux Plug and Play documentation.
 power/
@@ -372,14 +352,16 @@
 	- info on locking under a preemptive kernel.
 printk-formats.txt
 	- how to get printk format specifiers right
+process/
+	- how to work with the mainline kernel development process.
 pps/
 	- directory with information on the pulse-per-second support
+pti/
+	- directory with info on Intel MID PTI.
 ptp/
 	- directory with info on support for IEEE 1588 PTP clocks in Linux.
 pwm.txt
 	- info on the pulse width modulation driver subsystem
-ramoops.txt
-	- documentation of the ramoops oops/panic logging module.
 rapidio/
 	- directory with info on RapidIO packet-based fabric interconnect
 rbtree.txt
@@ -406,8 +388,6 @@
 	- directory that contains security-related info
 serial/
 	- directory with info on the low level serial API.
-serial-console.txt
-	- how to set up Linux with a serial line console as the default.
 sgi-ioc4.txt
 	- description of the SGI IOC4 PCI (multi function) device.
 sh/
@@ -416,24 +396,20 @@
 	-info on the smsc Keyboard Scan Expansion/GPIO Expansion device.
 sound/
 	- directory with info on sound card support.
-sparse.txt
-	- info on how to obtain and use the sparse tool for typechecking.
 spi/
 	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
-stable_api_nonsense.txt
-	- info on why the kernel does not have a stable in-kernel api or abi.
-stable_kernel_rules.txt
-	- rules and procedures for the -stable kernel releases.
+sphinx/
+	- no documentation here, just files required by Sphinx toolchain.
+sphinx-static/
+	- no documentation here, just files required by Sphinx toolchain.
 static-keys.txt
 	- info on how static keys allow debug code in hotpaths via patching
 svga.txt
 	- short guide on selecting video modes at boot via VGA BIOS.
-sysfs-rules.txt
-	- How not to use sysfs.
+sync_file.txt
+	- Sync file API guide.
 sysctl/
 	- directory with info on the /proc/sys/* files.
-sysrq.txt
-	- info on the magic SysRq key.
 target/
 	- directory with info on generating TCM v4 fabric .ko modules
 this_cpu_ops.txt
@@ -442,39 +418,29 @@
 	- directory with information on managing thermal issues (CPU/temp)
 trace/
 	- directory with info on tracing technologies within linux
+translations/
+	- translations of this document from English to another language
 unaligned-memory-access.txt
 	- info on how to avoid arch breaking unaligned memory access in code.
-unicode.txt
-	- info on the Unicode character/font mapping used in Linux.
 unshare.txt
 	- description of the Linux unshare system call.
 usb/
 	- directory with info regarding the Universal Serial Bus.
-vDSO/
-	- directory with info regarding virtual dynamic shared objects
 vfio.txt
 	- info on Virtual Function I/O used in guest/hypervisor instances.
-vgaarbiter.txt
-	- info on enable/disable the legacy decoding on different VGA devices
 video-output.txt
 	- sysfs class driver interface to enable/disable a video output device.
-video4linux/
-	- directory with info regarding video/TV/radio cards and linux.
 virtual/
 	- directory with information on the various linux virtualizations.
 vm/
 	- directory with info on the Linux vm code.
-vme_api.txt
-	- file relating info on the VME bus API in linux
-volatile-considered-harmful.txt
-	- Why the "volatile" type class should not be used
 w1/
 	- directory with documents regarding the 1-wire (w1) subsystem.
 watchdog/
 	- how to auto-reboot Linux if it has "fallen and can't get up". ;-)
 wimax/
 	- directory with info about Intel Wireless Wimax Connections
-workqueue.txt
+core-api/workqueue.rst
 	- information on the Concurrency Managed Workqueue implementation
 x86/x86_64/
 	- directory with info on Linux support for AMD x86-64 (Hammer) machines.
@@ -484,7 +450,5 @@
 	- directory with documents relating to arch/xtensa port/implementation
 xz.txt
 	- how to make use of the XZ data compression within linux kernel
-zh_CN/
-	- directory with Chinese translations of various documents
 zorro.txt
 	- info on writing drivers for Zorro bus devices found on Amigas.
diff --git a/Documentation/80211/conf.py b/Documentation/80211/conf.py
deleted file mode 100644
index 20c7c27..0000000
--- a/Documentation/80211/conf.py
+++ /dev/null
@@ -1,5 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Linux 802.11 Driver Developer's Guide"
-
-tags.add("subproject")
diff --git a/Documentation/80211/index.rst b/Documentation/80211/index.rst
deleted file mode 100644
index 90bba47..0000000
--- a/Documentation/80211/index.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-=====================================
-Linux 802.11 Driver Developer's Guide
-=====================================
-
-.. toctree::
-
-   introduction
-   cfg80211
-   mac80211
-   mac80211-advanced
-
-.. only::  subproject
-
-   Indices
-   =======
-
-   * :ref:`genindex`
diff --git a/Documentation/ABI/README b/Documentation/ABI/README
index 1fafc4b0..3121029 100644
--- a/Documentation/ABI/README
+++ b/Documentation/ABI/README
@@ -84,4 +84,4 @@
 
 - Kernel-internal symbols.  Do not rely on the presence, absence, location, or
   type of any kernel symbol, either in System.map files or the kernel binary
-  itself.  See Documentation/stable_api_nonsense.txt.
+  itself.  See Documentation/process/stable-api-nonsense.rst.
diff --git a/Documentation/ABI/stable/sysfs-devices b/Documentation/ABI/stable/sysfs-devices
index df449d7..35c457f 100644
--- a/Documentation/ABI/stable/sysfs-devices
+++ b/Documentation/ABI/stable/sysfs-devices
@@ -8,3 +8,17 @@
 		Any device associated with a device-tree node will have
 		an of_path symlink pointing to the corresponding device
 		node in /sys/firmware/devicetree/
+
+What:		/sys/devices/*/devspec
+Date:		October 2016
+Contact:	Device Tree mailing list <devicetree@vger.kernel.org>
+Description:
+		If CONFIG_OF is enabled, then this file is present. When
+		read, it returns full name of the device node.
+
+What:		/sys/devices/*/obppath
+Date:		October 2016
+Contact:	Device Tree mailing list <devicetree@vger.kernel.org>
+Description:
+		If CONFIG_OF is enabled, then this file is present. When
+		read, it returns full name of the device node.
diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block
index 71d184d..2da04ce 100644
--- a/Documentation/ABI/testing/sysfs-block
+++ b/Documentation/ABI/testing/sysfs-block
@@ -235,3 +235,45 @@
 		write_same_max_bytes is 0, write same is not supported
 		by the device.
 
+What:		/sys/block/<disk>/queue/write_zeroes_max_bytes
+Date:		November 2016
+Contact:	Chaitanya Kulkarni <chaitanya.kulkarni@wdc.com>
+Description:
+		Devices that support write zeroes operation in which a
+		single request can be issued to zero out the range of
+		contiguous blocks on storage without having any payload
+		in the request. This can be used to optimize writing zeroes
+		to the devices. write_zeroes_max_bytes indicates how many
+		bytes can be written in a single write zeroes command. If
+		write_zeroes_max_bytes is 0, write zeroes is not supported
+		by the device.
+
+What:		/sys/block/<disk>/queue/zoned
+Date:		September 2016
+Contact:	Damien Le Moal <damien.lemoal@hgst.com>
+Description:
+		zoned indicates if the device is a zoned block device
+		and the zone model of the device if it is indeed zoned.
+		The possible values indicated by zoned are "none" for
+		regular block devices and "host-aware" or "host-managed"
+		for zoned block devices. The characteristics of
+		host-aware and host-managed zoned block devices are
+		described in the ZBC (Zoned Block Commands) and ZAC
+		(Zoned Device ATA Command Set) standards. These standards
+		also define the "drive-managed" zone model. However,
+		since drive-managed zoned block devices do not support
+		zone commands, they will be treated as regular block
+		devices and zoned will report "none".
+
+What:		/sys/block/<disk>/queue/chunk_sectors
+Date:		September 2016
+Contact:	Hannes Reinecke <hare@suse.com>
+Description:
+		chunk_sectors has different meaning depending on the type
+		of the disk. For a RAID device (dm-raid), chunk_sectors
+		indicates the size in 512B sectors of the RAID volume
+		stripe segment. For a zoned block device, either
+		host-aware or host-managed, chunk_sectors indicates the
+		size of 512B sectors of the zones of the device, with
+		the eventual exception of the last zone of the device
+		which may be smaller.
diff --git a/Documentation/ABI/testing/sysfs-bus-fsl-mc b/Documentation/ABI/testing/sysfs-bus-fsl-mc
new file mode 100644
index 0000000..80256b8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-fsl-mc
@@ -0,0 +1,21 @@
+What:		/sys/bus/fsl-mc/drivers/.../bind
+Date:		December 2016
+Contact:	stuart.yoder@nxp.com
+Description:
+		Writing a device location to this file will cause
+		the driver to attempt to bind to the device found at
+		this location. The format for the location is Object.Id
+		and is the same as found in /sys/bus/fsl-mc/devices/.
+                For example:
+		# echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/bind
+
+What:		/sys/bus/fsl-mc/drivers/.../unbind
+Date:		December 2016
+Contact:	stuart.yoder@nxp.com
+Description:
+		Writing a device location to this file will cause the
+		driver to attempt to unbind from the device found at
+		this location. The format for the location is Object.Id
+		and is the same as found in /sys/bus/fsl-mc/devices/.
+                For example:
+		# echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/unbind
diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index fee35c0..b8f220f 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -329,6 +329,7 @@
 What:		/sys/bus/iio/devices/iio:deviceX/in_humidityrelative_scale
 What:		/sys/bus/iio/devices/iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_scale
 What:		/sys/bus/iio/devices/iio:deviceX/in_illuminance_scale
+What:		/sys/bus/iio/devices/iio:deviceX/in_countY_scale
 KernelVersion:	2.6.35
 Contact:	linux-iio@vger.kernel.org
 Description:
@@ -1579,3 +1580,20 @@
 Description:
 		Raw (unscaled no offset etc.) electric conductivity reading that
 		can be processed to siemens per meter.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_countY_raw
+KernelVersion:	4.9
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Raw counter device counts from channel Y. For quadrature
+		counters, multiplication by an available [Y]_scale results in
+		the counts of a single quadrature signal phase from channel Y.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_indexY_raw
+KernelVersion:	4.9
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Raw counter device index value from channel Y. This attribute
+		provides an absolute positional reference (e.g. a pulse once per
+		revolution) which may be used to home positional systems as
+		required.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector b/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector
new file mode 100644
index 0000000..2071f9b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector
@@ -0,0 +1,36 @@
+What:		/sys/bus/iio/devices/iio:deviceX/in_altvoltageY_invert
+Date:		October 2016
+KernelVersion:	4.9
+Contact:	Peter Rosin <peda@axentia.se>
+Description:
+		The DAC is used to find the peak level of an alternating
+		voltage input signal by a binary search using the output
+		of a comparator wired to an interrupt pin. Like so:
+		                           _
+		                          | \
+		     input +------>-------|+ \
+		                          |   \
+		            .-------.     |    }---.
+		            |       |     |   /    |
+		            |    dac|-->--|- /     |
+		            |       |     |_/      |
+		            |       |              |
+		            |       |              |
+		            |    irq|------<-------'
+		            |       |
+		            '-------'
+		The boolean invert attribute (0/1) should be set when the
+		input signal is centered around the maximum value of the
+		dac instead of zero. The envelope detector will search
+		from below in this case and will also invert the result.
+		The edge/level of the interrupt is also switched to its
+		opposite value.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_altvoltageY_compare_interval
+Date:		October 2016
+KernelVersion:	4.9
+Contact:	Peter Rosin <peda@axentia.se>
+Description:
+		Number of milliseconds to wait for the comparator in each
+		step of the binary search for the input peak level. Needs
+		to relate to the frequency of the input signal.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 b/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8
new file mode 100644
index 0000000..ba67652
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8
@@ -0,0 +1,125 @@
+What:		/sys/bus/iio/devices/iio:deviceX/in_count_count_direction_available
+What:		/sys/bus/iio/devices/iio:deviceX/in_count_count_mode_available
+What:		/sys/bus/iio/devices/iio:deviceX/in_count_noise_error_available
+What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
+What:		/sys/bus/iio/devices/iio:deviceX/in_index_index_polarity_available
+What:		/sys/bus/iio/devices/iio:deviceX/in_index_synchronous_mode_available
+KernelVersion:	4.9
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Discrete set of available values for the respective counter
+		configuration are listed in this file.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_countY_count_direction
+KernelVersion:	4.9
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Read-only attribute that indicates whether the counter for
+		channel Y is counting up or down.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_countY_count_mode
+KernelVersion:	4.9
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Count mode for channel Y. Four count modes are available:
+		normal, range limit, non-recycle, and modulo-n. The preset value
+		for channel Y is used by the count mode where required.
+
+		Normal:
+			Counting is continuous in either direction.
+
+		Range Limit:
+			An upper or lower limit is set, mimicking limit switches
+			in the mechanical counterpart. The upper limit is set to
+			the preset value, while the lower limit is set to 0. The
+			counter freezes at count = preset when counting up, and
+			at count = 0 when counting down. At either of these
+			limits, the counting is resumed only when the count
+			direction is reversed.
+
+		Non-recycle:
+			Counter is disabled whenever a 24-bit count overflow or
+			underflow takes place. The counter is re-enabled when a
+			new count value is loaded to the counter via a preset
+			operation or write to raw.
+
+		Modulo-N:
+			A count boundary is set between 0 and the preset value.
+			The counter is reset to 0 at count = preset when
+			counting up, while the counter is set to the preset
+			value at count = 0 when counting down; the counter does
+			not freeze at the bundary points, but counts
+			continuously throughout.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_countY_noise_error
+KernelVersion:	4.9
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Read-only attribute that indicates whether excessive noise is
+		present at the channel Y count inputs in quadrature clock mode;
+		irrelevant in non-quadrature clock mode.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_countY_preset
+KernelVersion:	4.9
+Contact:	linux-iio@vger.kernel.org
+Description:
+		If the counter device supports preset registers, the preset
+		count for channel Y is provided by this attribute.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_countY_quadrature_mode
+KernelVersion:	4.9
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Configure channel Y counter for non-quadrature or quadrature
+		clock mode. Selecting non-quadrature clock mode will disable
+		synchronous load mode. In quadrature clock mode, the channel Y
+		scale attribute selects the encoder phase division (scale of 1
+		selects full-cycle, scale of 0.5 selects half-cycle, scale of
+		0.25 selects quarter-cycle) processed by the channel Y counter.
+
+		Non-quadrature:
+			The filter and decoder circuit are bypassed. Encoder A
+			input serves as the count input and B as the UP/DOWN
+			direction control input, with B = 1 selecting UP Count
+			mode and B = 0 selecting Down Count mode.
+
+		Quadrature:
+			Encoder A and B inputs are digitally filtered and
+			decoded for UP/DN clock.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_countY_set_to_preset_on_index
+KernelVersion:	4.9
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Whether to set channel Y counter with channel Y preset value
+		when channel Y index input is active, or continuously count.
+		Valid attribute values are boolean.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_indexY_index_polarity
+KernelVersion:	4.9
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Active level of channel Y index input; irrelevant in
+		non-synchronous load mode.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_indexY_synchronous_mode
+KernelVersion:	4.9
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Configure channel Y counter for non-synchronous or synchronous
+		load mode. Synchronous load mode cannot be selected in
+		non-quadrature clock mode.
+
+		Non-synchronous:
+			A logic low level is the active level at this index
+			input. The index function (as enabled via
+			set_to_preset_on_index) is performed directly on the
+			active level of the index input.
+
+		Synchronous:
+			Intended for interfacing with encoder Index output in
+			quadrature clock mode. The active level is configured
+			via index_polarity. The index function (as enabled via
+			set_to_preset_on_index) is performed synchronously with
+			the quadrature clock on the active level of the index
+			input.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-cros-ec b/Documentation/ABI/testing/sysfs-bus-iio-cros-ec
new file mode 100644
index 0000000..297b972
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-cros-ec
@@ -0,0 +1,18 @@
+What:		/sys/bus/iio/devices/iio:deviceX/calibrate
+Date:		July 2015
+KernelVersion:	4.7
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Writing '1' will perform a FOC (Fast Online Calibration). The
+                corresponding calibration offsets can be read from *_calibbias
+                entries.
+
+What:		/sys/bus/iio/devices/iio:deviceX/location
+Date:		July 2015
+KernelVersion:	4.7
+Contact:	linux-iio@vger.kernel.org
+Description:
+		This attribute returns a string with the physical location where
+                the motion sensor is placed. For example, in a laptop a motion
+                sensor can be located on the base or on the lid. Current valid
+		values are 'base' and 'lid'.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dac-dpot-dac b/Documentation/ABI/testing/sysfs-bus-iio-dac-dpot-dac
new file mode 100644
index 0000000..580e93f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-dac-dpot-dac
@@ -0,0 +1,8 @@
+What:		/sys/bus/iio/devices/iio:deviceX/out_voltageY_raw_available
+Date:		October 2016
+KernelVersion:	4.9
+Contact:	Peter Rosin <peda@axentia.se>
+Description:
+		The range of available values represented as the minimum value,
+		the step and the maximum value, all enclosed in square brackets.
+		Example: [0 1 256]
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018 b/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018
new file mode 100644
index 0000000..f0ce0a0
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018
@@ -0,0 +1,19 @@
+What:		/sys/bus/iio/devices/iio:deviceX/proximity_on_chip_ambient_infrared_suppression
+Date:		January 2011
+KernelVersion:	2.6.37
+Contact:	linux-iio@vger.kernel.org
+Description:
+		From ISL29018 Data Sheet (FN6619.4, Oct 8, 2012) regarding the
+		infrared suppression:
+
+		Scheme 0, makes full n (4, 8, 12, 16) bits (unsigned) proximity
+		detection. The range of Scheme 0 proximity count is from 0 to
+		2^n. Logic 1 of this bit, Scheme 1, makes n-1 (3, 7, 11, 15)
+		bits (2's complementary) proximity_less_ambient detection. The
+		range of Scheme 1 proximity count is from -2^(n-1) to 2^(n-1).
+		The sign bit is extended for resolutions less than 16. While
+		Scheme 0 has wider dynamic range, Scheme 1 proximity detection
+		is less affected by the ambient IR noise variation.
+
+		0 Sensing IR from LED and ambient
+		1 Sensing IR from LED with ambient IR rejection
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-tsl2583 b/Documentation/ABI/testing/sysfs-bus-iio-light-tsl2583
new file mode 100644
index 0000000..a2e1996
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-light-tsl2583
@@ -0,0 +1,20 @@
+What:		/sys/bus/iio/devices/device[n]/in_illuminance_calibrate
+KernelVersion:	2.6.37
+Contact:	linux-iio@vger.kernel.org
+Description:
+		This property causes an internal calibration of the als gain trim
+		value which is later used in calculating illuminance in lux.
+
+What:		/sys/bus/iio/devices/device[n]/in_illuminance_lux_table
+KernelVersion:	2.6.37
+Contact:	linux-iio@vger.kernel.org
+Description:
+		This property gets/sets the table of coefficients
+		used in calculating illuminance in lux.
+
+What:		/sys/bus/iio/devices/device[n]/in_illuminance_input_target
+KernelVersion:	2.6.37
+Contact:	linux-iio@vger.kernel.org
+Description:
+		This property is the known externally illuminance (in lux).
+		It is used in the process of calibrating the device accuracy.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-potentiometer-mcp4531 b/Documentation/ABI/testing/sysfs-bus-iio-potentiometer-mcp4531
new file mode 100644
index 0000000..2a91fbe
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-potentiometer-mcp4531
@@ -0,0 +1,8 @@
+What:		/sys/bus/iio/devices/iio:deviceX/out_resistance_raw_available
+Date:		October 2016
+KernelVersion:	4.9
+Contact:	Peter Rosin <peda@axentia.se>
+Description:
+		The range of available values represented as the minimum value,
+		the step and the maximum value, all enclosed in square brackets.
+		Example: [0 1 256]
diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci
index b3bc50f..5a1732b 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci
+++ b/Documentation/ABI/testing/sysfs-bus-pci
@@ -294,3 +294,10 @@
 		a firmware bug to the system vendor.  Writing to this file
 		taints the kernel with TAINT_FIRMWARE_WORKAROUND, which
 		reduces the supportability of your system.
+
+What:		/sys/bus/pci/devices/.../revision
+Date:		November 2016
+Contact:	Emil Velikov <emil.l.velikov@gmail.com>
+Description:
+		This file contains the revision field of the the PCI device.
+		The value comes from device config space. The file is read only.
diff --git a/Documentation/ABI/testing/sysfs-bus-vfio-mdev b/Documentation/ABI/testing/sysfs-bus-vfio-mdev
new file mode 100644
index 0000000..452dbe3
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-vfio-mdev
@@ -0,0 +1,111 @@
+What:           /sys/.../<device>/mdev_supported_types/
+Date:           October 2016
+Contact:        Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+                This directory contains list of directories of currently
+		supported mediated device types and their details for
+		<device>. Supported type attributes are defined by the
+		vendor driver who registers with Mediated device framework.
+		Each supported type is a directory whose name is created
+		by adding the device driver string as a prefix to the
+		string provided by the vendor driver.
+
+What:           /sys/.../<device>/mdev_supported_types/<type-id>/
+Date:           October 2016
+Contact:        Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+                This directory gives details of supported type, like name,
+		description, available_instances, device_api etc.
+		'device_api' and 'available_instances' are mandatory
+		attributes to be provided by vendor driver. 'name',
+		'description' and other vendor driver specific attributes
+		are optional.
+
+What:           /sys/.../mdev_supported_types/<type-id>/create
+Date:           October 2016
+Contact:        Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+		Writing UUID to this file will create mediated device of
+		type <type-id> for parent device <device>. This is a
+		write-only file.
+		For example:
+		# echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" >	\
+		       /sys/devices/foo/mdev_supported_types/foo-1/create
+
+What:           /sys/.../mdev_supported_types/<type-id>/devices/
+Date:           October 2016
+Contact:        Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+		This directory contains symbolic links pointing to mdev
+		devices sysfs entries which are created of this <type-id>.
+
+What:           /sys/.../mdev_supported_types/<type-id>/available_instances
+Date:           October 2016
+Contact:        Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+		Reading this attribute will show the number of mediated
+		devices of type <type-id> that can be created. This is a
+		readonly file.
+Users:
+		Userspace applications interested in creating mediated
+		device of that type. Userspace application should check
+		the number of available instances could be created before
+		creating mediated device of this type.
+
+What:           /sys/.../mdev_supported_types/<type-id>/device_api
+Date:           October 2016
+Contact:        Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+		Reading this attribute will show VFIO device API supported
+		by this type. For example, "vfio-pci" for a PCI device,
+		"vfio-platform" for platform device.
+
+What:           /sys/.../mdev_supported_types/<type-id>/name
+Date:           October 2016
+Contact:        Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+		Reading this attribute will show human readable name of the
+		mediated device that will get created of type <type-id>.
+		This is optional attribute. For example: "Grid M60-0Q"
+Users:
+		Userspace applications interested in knowing the name of
+		a particular <type-id> that can help in understanding the
+		type of mediated device.
+
+What:           /sys/.../mdev_supported_types/<type-id>/description
+Date:           October 2016
+Contact:        Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+		Reading this attribute will show description of the type of
+		mediated device that will get created of type <type-id>.
+		This is optional attribute. For example:
+		"2 heads, 512M FB, 2560x1600 maximum resolution"
+Users:
+		Userspace applications interested in knowing the details of
+		a particular <type-id> that can help in understanding the
+		features provided by that type of mediated device.
+
+What:           /sys/.../<device>/<UUID>/
+Date:           October 2016
+Contact:        Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+		This directory represents device directory of mediated
+		device. It contains all the attributes related to mediated
+		device.
+
+What:           /sys/.../<device>/<UUID>/mdev_type
+Date:           October 2016
+Contact:        Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+		This is symbolic link pointing to supported type, <type-id>
+		directory of which this mediated device is created.
+
+What:           /sys/.../<device>/<UUID>/remove
+Date:           October 2016
+Contact:        Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+		Writing '1' to this file destroys the mediated device. The
+		vendor driver can fail the remove() callback if that device
+		is active and the vendor driver doesn't support hot unplug.
+		Example:
+		# echo 1 > /sys/bus/mdev/devices/<UUID>/remove
diff --git a/Documentation/ABI/testing/sysfs-class-fpga-bridge b/Documentation/ABI/testing/sysfs-class-fpga-bridge
new file mode 100644
index 0000000..312ae2c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-fpga-bridge
@@ -0,0 +1,11 @@
+What:		/sys/class/fpga_bridge/<bridge>/name
+Date:		January 2016
+KernelVersion:	4.5
+Contact:	Alan Tull <atull@opensource.altera.com>
+Description:	Name of low level FPGA bridge driver.
+
+What:		/sys/class/fpga_bridge/<bridge>/state
+Date:		January 2016
+KernelVersion:	4.5
+Contact:	Alan Tull <atull@opensource.altera.com>
+Description:	Show bridge state as "enabled" or "disabled"
diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led
index 86ace28..491cdee 100644
--- a/Documentation/ABI/testing/sysfs-class-led
+++ b/Documentation/ABI/testing/sysfs-class-led
@@ -4,16 +4,24 @@
 Contact:	Richard Purdie <rpurdie@rpsys.net>
 Description:
 		Set the brightness of the LED. Most LEDs don't
-		have hardware brightness support so will just be turned on for
+		have hardware brightness support, so will just be turned on for
 		non-zero brightness settings. The value is between 0 and
 		/sys/class/leds/<led>/max_brightness.
 
+		Writing 0 to this file clears active trigger.
+
+		Writing non-zero to this file while trigger is active changes the
+		top brightness trigger is going to use.
+
 What:		/sys/class/leds/<led>/max_brightness
 Date:		March 2006
 KernelVersion:	2.6.17
 Contact:	Richard Purdie <rpurdie@rpsys.net>
 Description:
-		Maximum brightness level for this led, default is 255 (LED_FULL).
+		Maximum brightness level for this LED, default is 255 (LED_FULL).
+
+		If the LED does not support different brightness levels, this
+		should be 1.
 
 What:		/sys/class/leds/<led>/trigger
 Date:		March 2006
@@ -21,7 +29,7 @@
 Contact:	Richard Purdie <rpurdie@rpsys.net>
 Description:
 		Set the trigger for this LED. A trigger is a kernel based source
-		of led events.
+		of LED events.
 		You can change triggers in a similar manner to the way an IO
 		scheduler is chosen. Trigger specific parameters can appear in
 		/sys/class/leds/<led> once a given trigger is selected. For
diff --git a/Documentation/ABI/testing/sysfs-class-mei b/Documentation/ABI/testing/sysfs-class-mei
index 80d9888..5096a82 100644
--- a/Documentation/ABI/testing/sysfs-class-mei
+++ b/Documentation/ABI/testing/sysfs-class-mei
@@ -29,3 +29,19 @@
 		Also number of registers varies between 1 and 6
 		depending on generation.
 
+What:		/sys/class/mei/meiN/hbm_ver
+Date:		Aug 2016
+KernelVersion:	4.9
+Contact:	Tomas Winkler <tomas.winkler@intel.com>
+Description:	Display the negotiated HBM protocol version.
+
+		The HBM protocol version negotiated
+		between the driver and the device.
+
+What:		/sys/class/mei/meiN/hbm_ver_drv
+Date:		Aug 2016
+KernelVersion:	4.9
+Contact:	Tomas Winkler <tomas.winkler@intel.com>
+Description:	Display the driver HBM protocol version.
+
+		The HBM protocol version supported by the driver.
diff --git a/Documentation/ABI/testing/sysfs-class-remoteproc b/Documentation/ABI/testing/sysfs-class-remoteproc
new file mode 100644
index 0000000..d188afe
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-remoteproc
@@ -0,0 +1,50 @@
+What:		/sys/class/remoteproc/.../firmware
+Date:		October 2016
+Contact:	Matt Redfearn <matt.redfearn@imgtec.com>
+Description:	Remote processor firmware
+
+		Reports the name of the firmware currently loaded to the
+		remote processor.
+
+		To change the running firmware, ensure the remote processor is
+		stopped (using /sys/class/remoteproc/.../state) and write a new filename.
+
+What:		/sys/class/remoteproc/.../state
+Date:		October 2016
+Contact:	Matt Redfearn <matt.redfearn@imgtec.com>
+Description:	Remote processor state
+
+		Reports the state of the remote processor, which will be one of:
+
+		"offline"
+		"suspended"
+		"running"
+		"crashed"
+		"invalid"
+
+		"offline" means the remote processor is powered off.
+
+		"suspended" means that the remote processor is suspended and
+		must be woken to receive messages.
+
+		"running" is the normal state of an available remote processor
+
+		"crashed" indicates that a problem/crash has been detected on
+		the remote processor.
+
+		"invalid" is returned if the remote processor is in an
+		unknown state.
+
+		Writing this file controls the state of the remote processor.
+		The following states can be written:
+
+		"start"
+		"stop"
+
+		Writing "start" will attempt to start the processor running the
+		firmware indicated by, or written to,
+		/sys/class/remoteproc/.../firmware. The remote processor should
+		transition to "running" state.
+
+		Writing "stop" will attempt to halt the remote processor and
+		return it to the "offline" state.
diff --git a/Documentation/ABI/testing/sysfs-devices-deferred_probe b/Documentation/ABI/testing/sysfs-devices-deferred_probe
new file mode 100644
index 0000000..58553d7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-deferred_probe
@@ -0,0 +1,12 @@
+What:		/sys/devices/.../deferred_probe
+Date:		August 2016
+Contact:	Ben Hutchings <ben.hutchings@codethink.co.uk>
+Description:
+		The /sys/devices/.../deferred_probe attribute is
+		present for all devices.  If a driver detects during
+		probing a device that a related device is not yet
+		ready, it may defer probing of the first device.  The
+		kernel will retry probing the first device after any
+		other device is successfully probed.  This attribute
+		reads as 1 if probing of this device is currently
+		deferred, or 0 otherwise.
diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab
index 91bd6ca..2cc0a72 100644
--- a/Documentation/ABI/testing/sysfs-kernel-slab
+++ b/Documentation/ABI/testing/sysfs-kernel-slab
@@ -347,7 +347,7 @@
 		because of fragmentation, SLUB will retry with the minimum order
 		possible depending on its characteristics.
 		When debug_guardpage_minorder=N (N > 0) parameter is specified
-		(see Documentation/kernel-parameters.txt), the minimum possible
+		(see Documentation/admin-guide/kernel-parameters.rst), the minimum possible
 		order is used and this sysfs entry can not be used to change
 		the order at run time.
 
diff --git a/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2 b/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2
new file mode 100644
index 0000000..6212697
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2
@@ -0,0 +1,15 @@
+What:		/sys/devices/platform/<phy-name>/role
+Date:		October 2016
+KernelVersion:	4.10
+Contact:	Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com>
+Description:
+		This file can be read and write.
+		The file can show/change the phy mode for role swap of usb.
+
+		Write the following strings to change the mode:
+		 "host" - switching mode from peripheral to host.
+		 "peripheral" - switching mode from host to peripheral.
+
+		Read the file, then it shows the following strings:
+		 "host" - The mode is host now.
+		 "peripheral" - The mode is peripheral now.
diff --git a/Documentation/ABI/testing/sysfs-platform-sst-atom b/Documentation/ABI/testing/sysfs-platform-sst-atom
new file mode 100644
index 0000000..0d07c03
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-sst-atom
@@ -0,0 +1,17 @@
+What:		/sys/devices/platform/8086%x:00/firmware_version
+Date:		November 2016
+KernelVersion:	4.10
+Contact:	"Sebastien Guiriec" <sebastien.guiriec@intel.com>
+Description:
+		LPE Firmware version for SST driver on all atom
+		plaforms (BYT/CHT/Merrifield/BSW).
+		If the FW has never been loaded it will display:
+			"FW not yet loaded"
+		If FW has been loaded it will display:
+			"v01.aa.bb.cc"
+		aa: Major version is reflecting SoC version:
+			0d: BYT FW
+			0b: BSW FW
+			07: Merrifield FW
+		bb: Minor version
+		cc: Build version
diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power
index 50b368d..f523e5a 100644
--- a/Documentation/ABI/testing/sysfs-power
+++ b/Documentation/ABI/testing/sysfs-power
@@ -7,30 +7,35 @@
 		subsystem.
 
 What:		/sys/power/state
-Date:		May 2014
+Date:		November 2016
 Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
 Description:
 		The /sys/power/state file controls system sleep states.
 		Reading from this file returns the available sleep state
-		labels, which may be "mem", "standby", "freeze" and "disk"
-		(hibernation).  The meanings of the first three labels depend on
-		the relative_sleep_states command line argument as follows:
-		 1) relative_sleep_states = 1
-		    "mem", "standby", "freeze" represent non-hibernation sleep
-		    states from the deepest ("mem", always present) to the
-		    shallowest ("freeze").  "standby" and "freeze" may or may
-		    not be present depending on the capabilities of the
-		    platform.  "freeze" can only be present if "standby" is
-		    present.
-		 2) relative_sleep_states = 0 (default)
-		    "mem" - "suspend-to-RAM", present if supported.
-		    "standby" - "power-on suspend", present if supported.
-		    "freeze" - "suspend-to-idle", always present.
+		labels, which may be "mem" (suspend), "standby" (power-on
+		suspend), "freeze" (suspend-to-idle) and "disk" (hibernation).
 
-		Writing to this file one of these strings causes the system to
-		transition into the corresponding state, if available.  See
-		Documentation/power/states.txt for a description of what
-		"suspend-to-RAM", "power-on suspend" and "suspend-to-idle" mean.
+		Writing one of the above strings to this file causes the system
+		to transition into the corresponding state, if available.
+
+		See Documentation/power/states.txt for more information.
+
+What:		/sys/power/mem_sleep
+Date:		November 2016
+Contact:	Rafael J. Wysocki <rjw@rjwysocki.net>
+Description:
+		The /sys/power/mem_sleep file controls the operating mode of
+		system suspend.  Reading from it returns the available modes
+		as "s2idle" (always present), "shallow" and "deep" (present if
+		supported).  The mode that will be used on subsequent attempts
+		to suspend the system (by writing "mem" to the /sys/power/state
+		file described above) is enclosed in square brackets.
+
+		Writing one of the above strings to this file causes the mode
+		represented by it to be used on subsequent attempts to suspend
+		the system.
+
+		See Documentation/power/states.txt for more information.
 
 What:		/sys/power/disk
 Date:		September 2006
diff --git a/Documentation/BUG-HUNTING b/Documentation/BUG-HUNTING
deleted file mode 100644
index 65022a8..0000000
--- a/Documentation/BUG-HUNTING
+++ /dev/null
@@ -1,246 +0,0 @@
-Table of contents
-=================
-
-Last updated: 20 December 2005
-
-Contents
-========
-
-- Introduction
-- Devices not appearing
-- Finding patch that caused a bug
--- Finding using git-bisect
--- Finding it the old way
-- Fixing the bug
-
-Introduction
-============
-
-Always try the latest kernel from kernel.org and build from source. If you are
-not confident in doing that please report the bug to your distribution vendor
-instead of to a kernel developer.
-
-Finding bugs is not always easy. Have a go though. If you can't find it don't
-give up. Report as much as you have found to the relevant maintainer. See
-MAINTAINERS for who that is for the subsystem you have worked on.
-
-Before you submit a bug report read REPORTING-BUGS.
-
-Devices not appearing
-=====================
-
-Often this is caused by udev. Check that first before blaming it on the
-kernel.
-
-Finding patch that caused a bug
-===============================
-
-
-
-Finding using git-bisect
-------------------------
-
-Using the provided tools with git makes finding bugs easy provided the bug is
-reproducible.
-
-Steps to do it:
-- start using git for the kernel source
-- read the man page for git-bisect
-- have fun
-
-Finding it the old way
-----------------------
-
-[Sat Mar  2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)]
-
-This is how to track down a bug if you know nothing about kernel hacking.
-It's a brute force approach but it works pretty well.
-
-You need:
-
-        . A reproducible bug - it has to happen predictably (sorry)
-        . All the kernel tar files from a revision that worked to the
-          revision that doesn't
-
-You will then do:
-
-        . Rebuild a revision that you believe works, install, and verify that.
-        . Do a binary search over the kernels to figure out which one
-          introduced the bug.  I.e., suppose 1.3.28 didn't have the bug, but
-          you know that 1.3.69 does.  Pick a kernel in the middle and build
-          that, like 1.3.50.  Build & test; if it works, pick the mid point
-          between .50 and .69, else the mid point between .28 and .50.
-        . You'll narrow it down to the kernel that introduced the bug.  You
-          can probably do better than this but it gets tricky.
-
-        . Narrow it down to a subdirectory
-
-          - Copy kernel that works into "test".  Let's say that 3.62 works,
-            but 3.63 doesn't.  So you diff -r those two kernels and come
-            up with a list of directories that changed.  For each of those
-            directories:
-
-                Copy the non-working directory next to the working directory
-                as "dir.63".
-                One directory at time, try moving the working directory to
-                "dir.62" and mv dir.63 dir"time, try
-
-                        mv dir dir.62
-                        mv dir.63 dir
-                        find dir -name '*.[oa]' -print | xargs rm -f
-
-                And then rebuild and retest.  Assuming that all related
-                changes were contained in the sub directory, this should
-                isolate the change to a directory.
-
-                Problems: changes in header files may have occurred; I've
-                found in my case that they were self explanatory - you may
-                or may not want to give up when that happens.
-
-        . Narrow it down to a file
-
-          - You can apply the same technique to each file in the directory,
-            hoping that the changes in that file are self contained.
-
-        . Narrow it down to a routine
-
-          - You can take the old file and the new file and manually create
-            a merged file that has
-
-                #ifdef VER62
-                routine()
-                {
-                        ...
-                }
-                #else
-                routine()
-                {
-                        ...
-                }
-                #endif
-
-            And then walk through that file, one routine at a time and
-            prefix it with
-
-                #define VER62
-                /* both routines here */
-                #undef VER62
-
-            Then recompile, retest, move the ifdefs until you find the one
-            that makes the difference.
-
-Finally, you take all the info that you have, kernel revisions, bug
-description, the extent to which you have narrowed it down, and pass
-that off to whomever you believe is the maintainer of that section.
-A post to linux.dev.kernel isn't such a bad idea if you've done some
-work to narrow it down.
-
-If you get it down to a routine, you'll probably get a fix in 24 hours.
-
-My apologies to Linus and the other kernel hackers for describing this
-brute force approach, it's hardly what a kernel hacker would do.  However,
-it does work and it lets non-hackers help fix bugs.  And it is cool
-because Linux snapshots will let you do this - something that you can't
-do with vendor supplied releases.
-
-Fixing the bug
-==============
-
-Nobody is going to tell you how to fix bugs. Seriously. You need to work it
-out. But below are some hints on how to use the tools.
-
-To debug a kernel, use objdump and look for the hex offset from the crash
-output to find the valid line of code/assembler. Without debug symbols, you
-will see the assembler code for the routine shown, but if your kernel has
-debug symbols the C code will also be available. (Debug symbols can be enabled
-in the kernel hacking menu of the menu configuration.) For example:
-
-    objdump -r -S -l --disassemble net/dccp/ipv4.o
-
-NB.: you need to be at the top level of the kernel tree for this to pick up
-your C files.
-
-If you don't have access to the code you can also debug on some crash dumps
-e.g. crash dump output as shown by Dave Miller.
-
->    EIP is at ip_queue_xmit+0x14/0x4c0
->     ...
->    Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00
->    00 00 55 57  56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08
->    <8b> 83 3c 01 00 00 89 44  24 14 8b 45 28 85 c0 89 44 24 18 0f 85
->
->    Put the bytes into a "foo.s" file like this:
->
->           .text
->           .globl foo
->    foo:
->           .byte  .... /* bytes from Code: part of OOPS dump */
->
->    Compile it with "gcc -c -o foo.o foo.s" then look at the output of
->    "objdump --disassemble foo.o".
->
->    Output:
->
->    ip_queue_xmit:
->        push       %ebp
->        push       %edi
->        push       %esi
->        push       %ebx
->        sub        $0xbc, %esp
->        mov        0xd0(%esp), %ebp        ! %ebp = arg0 (skb)
->        mov        0x8(%ebp), %ebx         ! %ebx = skb->sk
->        mov        0x13c(%ebx), %eax       ! %eax = inet_sk(sk)->opt
-
-In addition, you can use GDB to figure out the exact file and line
-number of the OOPS from the vmlinux file. If you have
-CONFIG_DEBUG_INFO enabled, you can simply copy the EIP value from the
-OOPS:
-
- EIP:    0060:[<c021e50e>]    Not tainted VLI
-
-And use GDB to translate that to human-readable form:
-
-  gdb vmlinux
-  (gdb) l *0xc021e50e
-
-If you don't have CONFIG_DEBUG_INFO enabled, you use the function
-offset from the OOPS:
-
- EIP is at vt_ioctl+0xda8/0x1482
-
-And recompile the kernel with CONFIG_DEBUG_INFO enabled:
-
-  make vmlinux
-  gdb vmlinux
-  (gdb) p vt_ioctl
-  (gdb) l *(0x<address of vt_ioctl> + 0xda8)
-or, as one command
-  (gdb) l *(vt_ioctl + 0xda8)
-
-If you have a call trace, such as :-
->Call Trace:
-> [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5
-> [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e
-> [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee
-> ...
-this shows the problem in the :jbd: module. You can load that module in gdb
-and list the relevant code.
-  gdb fs/jbd/jbd.ko
-  (gdb) p log_wait_commit
-  (gdb) l *(0x<address> + 0xa3)
-or
-  (gdb) l *(log_wait_commit + 0xa3)
-
-
-Another very useful option of the Kernel Hacking section in menuconfig is
-Debug memory allocations. This will help you see whether data has been
-initialised and not set before use etc. To see the values that get assigned
-with this look at mm/slab.c and search for POISON_INUSE. When using this an
-Oops will often show the poisoned data instead of zero which is the default.
-
-Once you have worked out a fix please submit it upstream. After all open
-source is about sharing what you do and don't you want to be recognised for
-your genius?
-
-Please do read Documentation/SubmittingPatches though to help your code get
-accepted.
diff --git a/Documentation/Changes b/Documentation/Changes
deleted file mode 100644
index 22797a1..0000000
--- a/Documentation/Changes
+++ /dev/null
@@ -1,485 +0,0 @@
-.. _changes:
-
-Minimal requerements to compile the Kernel
-++++++++++++++++++++++++++++++++++++++++++
-
-Intro
-=====
-
-This document is designed to provide a list of the minimum levels of
-software necessary to run the 4.x kernels.
-
-This document is originally based on my "Changes" file for 2.0.x kernels
-and therefore owes credit to the same people as that file (Jared Mauch,
-Axel Boldt, Alessandro Sigala, and countless other users all over the
-'net).
-
-Current Minimal Requirements
-****************************
-
-Upgrade to at **least** these software revisions before thinking you've
-encountered a bug!  If you're unsure what version you're currently
-running, the suggested command should tell you.
-
-Again, keep in mind that this list assumes you are already functionally
-running a Linux kernel.  Also, not all tools are necessary on all
-systems; obviously, if you don't have any ISDN hardware, for example,
-you probably needn't concern yourself with isdn4k-utils.
-
-====================== ===============  ========================================
-        Program        Minimal version       Command to check the version
-====================== ===============  ========================================
-GNU C                  3.2              gcc --version
-GNU make               3.80             make --version
-binutils               2.12             ld -v
-util-linux             2.10o            fdformat --version
-module-init-tools      0.9.10           depmod -V
-e2fsprogs              1.41.4           e2fsck -V
-jfsutils               1.1.3            fsck.jfs -V
-reiserfsprogs          3.6.3            reiserfsck -V
-xfsprogs               2.6.0            xfs_db -V
-squashfs-tools         4.0              mksquashfs -version
-btrfs-progs            0.18             btrfsck
-pcmciautils            004              pccardctl -V
-quota-tools            3.09             quota -V
-PPP                    2.4.0            pppd --version
-isdn4k-utils           3.1pre1          isdnctrl 2>&1|grep version
-nfs-utils              1.0.5            showmount --version
-procps                 3.2.0            ps --version
-oprofile               0.9              oprofiled --version
-udev                   081              udevd --version
-grub                   0.93             grub --version || grub-install --version
-mcelog                 0.6              mcelog --version
-iptables               1.4.2            iptables -V
-openssl & libcrypto    1.0.0            openssl version
-bc                     1.06.95          bc --version
-Sphinx\ [#f1]_	       1.2		sphinx-build --version
-====================== ===============  ========================================
-
-.. [#f1] Sphinx is needed only to build the Kernel documentation
-
-Kernel compilation
-******************
-
-GCC
----
-
-The gcc version requirements may vary depending on the type of CPU in your
-computer.
-
-Make
-----
-
-You will need GNU make 3.80 or later to build the kernel.
-
-Binutils
---------
-
-Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for
-assembling the 16-bit boot code, removing the need for ``as86`` to compile
-your kernel.  This change does, however, mean that you need a recent
-release of binutils.
-
-Perl
-----
-
-You will need perl 5 and the following modules: ``Getopt::Long``,
-``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel.
-
-BC
---
-
-You will need bc to build kernels 3.10 and higher
-
-
-OpenSSL
--------
-
-Module signing and external certificate handling use the OpenSSL program and
-crypto library to do key creation and signature generation.
-
-You will need openssl to build kernels 3.7 and higher if module signing is
-enabled.  You will also need openssl development packages to build kernels 4.3
-and higher.
-
-
-System utilities
-****************
-
-Architectural changes
----------------------
-
-DevFS has been obsoleted in favour of udev
-(http://www.kernel.org/pub/linux/utils/kernel/hotplug/)
-
-32-bit UID support is now in place.  Have fun!
-
-Linux documentation for functions is transitioning to inline
-documentation via specially-formatted comments near their
-definitions in the source.  These comments can be combined with the
-SGML templates in the Documentation/DocBook directory to make DocBook
-files, which can then be converted by DocBook stylesheets to PostScript,
-HTML, PDF files, and several other formats.  In order to convert from
-DocBook format to a format of your choice, you'll need to install Jade as
-well as the desired DocBook stylesheets.
-
-Util-linux
-----------
-
-New versions of util-linux provide ``fdisk`` support for larger disks,
-support new options to mount, recognize more supported partition
-types, have a fdformat which works with 2.4 kernels, and similar goodies.
-You'll probably want to upgrade.
-
-Ksymoops
---------
-
-If the unthinkable happens and your kernel oopses, you may need the
-ksymoops tool to decode it, but in most cases you don't.
-It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so
-that it produces readable dumps that can be used as-is (this also
-produces better output than ksymoops).  If for some reason your kernel
-is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and
-reproduce the Oops with that option, then you can still decode that Oops
-with ksymoops.
-
-Module-Init-Tools
------------------
-
-A new module loader is now in the kernel that requires ``module-init-tools``
-to use.  It is backward compatible with the 2.4.x series kernels.
-
-Mkinitrd
---------
-
-These changes to the ``/lib/modules`` file tree layout also require that
-mkinitrd be upgraded.
-
-E2fsprogs
----------
-
-The latest version of ``e2fsprogs`` fixes several bugs in fsck and
-debugfs.  Obviously, it's a good idea to upgrade.
-
-JFSutils
---------
-
-The ``jfsutils`` package contains the utilities for the file system.
-The following utilities are available:
-
-- ``fsck.jfs`` - initiate replay of the transaction log, and check
-  and repair a JFS formatted partition.
-
-- ``mkfs.jfs`` - create a JFS formatted partition.
-
-- other file system utilities are also available in this package.
-
-Reiserfsprogs
--------------
-
-The reiserfsprogs package should be used for reiserfs-3.6.x
-(Linux kernels 2.4.x). It is a combined package and contains working
-versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and
-``reiserfsck``. These utils work on both i386 and alpha platforms.
-
-Xfsprogs
---------
-
-The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the
-``xfs_repair`` utilities, among others, for the XFS filesystem.  It is
-architecture independent and any version from 2.0.0 onward should
-work correctly with this version of the XFS kernel code (2.6.0 or
-later is recommended, due to some significant improvements).
-
-PCMCIAutils
------------
-
-PCMCIAutils replaces ``pcmcia-cs``. It properly sets up
-PCMCIA sockets at system startup and loads the appropriate modules
-for 16-bit PCMCIA devices if the kernel is modularized and the hotplug
-subsystem is used.
-
-Quota-tools
------------
-
-Support for 32 bit uid's and gid's is required if you want to use
-the newer version 2 quota format.  Quota-tools version 3.07 and
-newer has this support.  Use the recommended version or newer
-from the table above.
-
-Intel IA32 microcode
---------------------
-
-A driver has been added to allow updating of Intel IA32 microcode,
-accessible as a normal (misc) character device.  If you are not using
-udev you may need to::
-
-  mkdir /dev/cpu
-  mknod /dev/cpu/microcode c 10 184
-  chmod 0644 /dev/cpu/microcode
-
-as root before you can use this.  You'll probably also want to
-get the user-space microcode_ctl utility to use with this.
-
-udev
-----
-
-``udev`` is a userspace application for populating ``/dev`` dynamically with
-only entries for devices actually present. ``udev`` replaces the basic
-functionality of devfs, while allowing persistent device naming for
-devices.
-
-FUSE
-----
-
-Needs libfuse 2.4.0 or later.  Absolute minimum is 2.3.0 but mount
-options ``direct_io`` and ``kernel_cache`` won't work.
-
-Networking
-**********
-
-General changes
----------------
-
-If you have advanced network configuration needs, you should probably
-consider using the network tools from ip-route2.
-
-Packet Filter / NAT
--------------------
-The packet filtering and NAT code uses the same tools like the previous 2.4.x
-kernel series (iptables).  It still includes backwards-compatibility modules
-for 2.2.x-style ipchains and 2.0.x-style ipfwadm.
-
-PPP
----
-
-The PPP driver has been restructured to support multilink and to
-enable it to operate over diverse media layers.  If you use PPP,
-upgrade pppd to at least 2.4.0.
-
-If you are not using udev, you must have the device file /dev/ppp
-which can be made by::
-
-  mknod /dev/ppp c 108 0
-
-as root.
-
-Isdn4k-utils
-------------
-
-Due to changes in the length of the phone number field, isdn4k-utils
-needs to be recompiled or (preferably) upgraded.
-
-NFS-utils
----------
-
-In ancient (2.4 and earlier) kernels, the nfs server needed to know
-about any client that expected to be able to access files via NFS.  This
-information would be given to the kernel by ``mountd`` when the client
-mounted the filesystem, or by ``exportfs`` at system startup.  exportfs
-would take information about active clients from ``/var/lib/nfs/rmtab``.
-
-This approach is quite fragile as it depends on rmtab being correct
-which is not always easy, particularly when trying to implement
-fail-over.  Even when the system is working well, ``rmtab`` suffers from
-getting lots of old entries that never get removed.
-
-With modern kernels we have the option of having the kernel tell mountd
-when it gets a request from an unknown host, and mountd can give
-appropriate export information to the kernel.  This removes the
-dependency on ``rmtab`` and means that the kernel only needs to know about
-currently active clients.
-
-To enable this new functionality, you need to::
-
-  mount -t nfsd nfsd /proc/fs/nfsd
-
-before running exportfs or mountd.  It is recommended that all NFS
-services be protected from the internet-at-large by a firewall where
-that is possible.
-
-mcelog
-------
-
-On x86 kernels the mcelog utility is needed to process and log machine check
-events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors
-reported by the CPU. Processing them is strongly encouraged.
-
-Kernel documentation
-********************
-
-Sphinx
-------
-
-The ReST markups currently used by the Documentation/ files are meant to be
-built with ``Sphinx`` version 1.2 or upper. If you're desiring to build
-PDF outputs, it is recommended to use version 1.4.6.
-
-.. note::
-
-  Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX``
-  version 3.14159265. Depending on the distribution, you may also need
-  to install a series of ``texlive`` packages that provide the minimal
-  set of functionalities required for ``XeLaTex`` to work.
-
-Other tools
------------
-
-In order to produce documentation from DocBook, you'll also need ``xmlto``.
-Please notice, however, that we're currently migrating all documents to use
-``Sphinx``.
-
-Getting updated software
-========================
-
-Kernel compilation
-******************
-
-gcc
----
-
-- <ftp://ftp.gnu.org/gnu/gcc/>
-
-Make
-----
-
-- <ftp://ftp.gnu.org/gnu/make/>
-
-Binutils
---------
-
-- <ftp://ftp.kernel.org/pub/linux/devel/binutils/>
-
-OpenSSL
--------
-
-- <https://www.openssl.org/>
-
-System utilities
-****************
-
-Util-linux
-----------
-
-- <ftp://ftp.kernel.org/pub/linux/utils/util-linux/>
-
-Ksymoops
---------
-
-- <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>
-
-Module-Init-Tools
------------------
-
-- <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/>
-
-Mkinitrd
---------
-
-- <https://code.launchpad.net/initrd-tools/main>
-
-E2fsprogs
----------
-
-- <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz>
-
-JFSutils
---------
-
-- <http://jfs.sourceforge.net/>
-
-Reiserfsprogs
--------------
-
-- <http://www.kernel.org/pub/linux/utils/fs/reiserfs/>
-
-Xfsprogs
---------
-
-- <ftp://oss.sgi.com/projects/xfs/>
-
-Pcmciautils
------------
-
-- <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/>
-
-Quota-tools
------------
-
-- <http://sourceforge.net/projects/linuxquota/>
-
-DocBook Stylesheets
--------------------
-
-- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
-
-XMLTO XSLT Frontend
--------------------
-
-- <http://cyberelk.net/tim/xmlto/>
-
-Intel P6 microcode
-------------------
-
-- <https://downloadcenter.intel.com/>
-
-udev
-----
-
-- <http://www.freedesktop.org/software/systemd/man/udev.html>
-
-FUSE
-----
-
-- <http://sourceforge.net/projects/fuse>
-
-mcelog
-------
-
-- <http://www.mcelog.org/>
-
-Networking
-**********
-
-PPP
----
-
-- <ftp://ftp.samba.org/pub/ppp/>
-
-Isdn4k-utils
-------------
-
-- <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
-
-NFS-utils
----------
-
-- <http://sourceforge.net/project/showfiles.php?group_id=14>
-
-Iptables
---------
-
-- <http://www.iptables.org/downloads.html>
-
-Ip-route2
----------
-
-- <https://www.kernel.org/pub/linux/utils/net/iproute2/>
-
-OProfile
---------
-
-- <http://oprofile.sf.net/download/>
-
-NFS-Utils
----------
-
-- <http://nfs.sourceforge.net/>
-
-Kernel documentation
-********************
-
-Sphinx
-------
-
-- <http://www.sphinx-doc.org/>
diff --git a/Documentation/Changes b/Documentation/Changes
new file mode 120000
index 0000000..7564ae1
--- /dev/null
+++ b/Documentation/Changes
@@ -0,0 +1 @@
+process/changes.rst
\ No newline at end of file
diff --git a/Documentation/CodeOfConflict b/Documentation/CodeOfConflict
deleted file mode 100644
index 49a8ecc..0000000
--- a/Documentation/CodeOfConflict
+++ /dev/null
@@ -1,27 +0,0 @@
-Code of Conflict
-----------------
-
-The Linux kernel development effort is a very personal process compared
-to "traditional" ways of developing software.  Your code and ideas
-behind it will be carefully reviewed, often resulting in critique and
-criticism.  The review will almost always require improvements to the
-code before it can be included in the kernel.  Know that this happens
-because everyone involved wants to see the best possible solution for
-the overall success of Linux.  This development process has been proven
-to create the most robust operating system kernel ever, and we do not
-want to do anything to cause the quality of submission and eventual
-result to ever decrease.
-
-If however, anyone feels personally abused, threatened, or otherwise
-uncomfortable due to this process, that is not acceptable.  If so,
-please contact the Linux Foundation's Technical Advisory Board at
-<tab@lists.linux-foundation.org>, or the individual members, and they
-will work to resolve the issue to the best of their ability.  For more
-information on who is on the Technical Advisory Board and what their
-role is, please see:
-	http://www.linuxfoundation.org/projects/linux/tab
-
-As a reviewer of code, please strive to keep things civil and focused on
-the technical issues involved.  We are all humans, and frustrations can
-be high on both sides of the process.  Try to keep in mind the immortal
-words of Bill and Ted, "Be excellent to each other."
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 9c61c03..320983c 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -1,1062 +1 @@
-.. _codingstyle:
-
-Linux kernel coding style
-=========================
-
-This is a short document describing the preferred coding style for the
-linux kernel.  Coding style is very personal, and I won't **force** my
-views on anybody, but this is what goes for anything that I have to be
-able to maintain, and I'd prefer it for most other things too.  Please
-at least consider the points made here.
-
-First off, I'd suggest printing out a copy of the GNU coding standards,
-and NOT read it.  Burn them, it's a great symbolic gesture.
-
-Anyway, here goes:
-
-
-1) Indentation
---------------
-
-Tabs are 8 characters, and thus indentations are also 8 characters.
-There are heretic movements that try to make indentations 4 (or even 2!)
-characters deep, and that is akin to trying to define the value of PI to
-be 3.
-
-Rationale: The whole idea behind indentation is to clearly define where
-a block of control starts and ends.  Especially when you've been looking
-at your screen for 20 straight hours, you'll find it a lot easier to see
-how the indentation works if you have large indentations.
-
-Now, some people will claim that having 8-character indentations makes
-the code move too far to the right, and makes it hard to read on a
-80-character terminal screen.  The answer to that is that if you need
-more than 3 levels of indentation, you're screwed anyway, and should fix
-your program.
-
-In short, 8-char indents make things easier to read, and have the added
-benefit of warning you when you're nesting your functions too deep.
-Heed that warning.
-
-The preferred way to ease multiple indentation levels in a switch statement is
-to align the ``switch`` and its subordinate ``case`` labels in the same column
-instead of ``double-indenting`` the ``case`` labels.  E.g.:
-
-.. code-block:: c
-
-	switch (suffix) {
-	case 'G':
-	case 'g':
-		mem <<= 30;
-		break;
-	case 'M':
-	case 'm':
-		mem <<= 20;
-		break;
-	case 'K':
-	case 'k':
-		mem <<= 10;
-		/* fall through */
-	default:
-		break;
-	}
-
-Don't put multiple statements on a single line unless you have
-something to hide:
-
-.. code-block:: c
-
-	if (condition) do_this;
-	  do_something_everytime;
-
-Don't put multiple assignments on a single line either.  Kernel coding style
-is super simple.  Avoid tricky expressions.
-
-Outside of comments, documentation and except in Kconfig, spaces are never
-used for indentation, and the above example is deliberately broken.
-
-Get a decent editor and don't leave whitespace at the end of lines.
-
-
-2) Breaking long lines and strings
-----------------------------------
-
-Coding style is all about readability and maintainability using commonly
-available tools.
-
-The limit on the length of lines is 80 columns and this is a strongly
-preferred limit.
-
-Statements longer than 80 columns will be broken into sensible chunks, unless
-exceeding 80 columns significantly increases readability and does not hide
-information. Descendants are always substantially shorter than the parent and
-are placed substantially to the right. The same applies to function headers
-with a long argument list. However, never break user-visible strings such as
-printk messages, because that breaks the ability to grep for them.
-
-
-3) Placing Braces and Spaces
-----------------------------
-
-The other issue that always comes up in C styling is the placement of
-braces.  Unlike the indent size, there are few technical reasons to
-choose one placement strategy over the other, but the preferred way, as
-shown to us by the prophets Kernighan and Ritchie, is to put the opening
-brace last on the line, and put the closing brace first, thusly:
-
-.. code-block:: c
-
-	if (x is true) {
-		we do y
-	}
-
-This applies to all non-function statement blocks (if, switch, for,
-while, do).  E.g.:
-
-.. code-block:: c
-
-	switch (action) {
-	case KOBJ_ADD:
-		return "add";
-	case KOBJ_REMOVE:
-		return "remove";
-	case KOBJ_CHANGE:
-		return "change";
-	default:
-		return NULL;
-	}
-
-However, there is one special case, namely functions: they have the
-opening brace at the beginning of the next line, thus:
-
-.. code-block:: c
-
-	int function(int x)
-	{
-		body of function
-	}
-
-Heretic people all over the world have claimed that this inconsistency
-is ...  well ...  inconsistent, but all right-thinking people know that
-(a) K&R are **right** and (b) K&R are right.  Besides, functions are
-special anyway (you can't nest them in C).
-
-Note that the closing brace is empty on a line of its own, **except** in
-the cases where it is followed by a continuation of the same statement,
-ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
-this:
-
-.. code-block:: c
-
-	do {
-		body of do-loop
-	} while (condition);
-
-and
-
-.. code-block:: c
-
-	if (x == y) {
-		..
-	} else if (x > y) {
-		...
-	} else {
-		....
-	}
-
-Rationale: K&R.
-
-Also, note that this brace-placement also minimizes the number of empty
-(or almost empty) lines, without any loss of readability.  Thus, as the
-supply of new-lines on your screen is not a renewable resource (think
-25-line terminal screens here), you have more empty lines to put
-comments on.
-
-Do not unnecessarily use braces where a single statement will do.
-
-.. code-block:: c
-
-	if (condition)
-		action();
-
-and
-
-.. code-block:: none
-
-	if (condition)
-		do_this();
-	else
-		do_that();
-
-This does not apply if only one branch of a conditional statement is a single
-statement; in the latter case use braces in both branches:
-
-.. code-block:: c
-
-	if (condition) {
-		do_this();
-		do_that();
-	} else {
-		otherwise();
-	}
-
-3.1) Spaces
-***********
-
-Linux kernel style for use of spaces depends (mostly) on
-function-versus-keyword usage.  Use a space after (most) keywords.  The
-notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
-somewhat like functions (and are usually used with parentheses in Linux,
-although they are not required in the language, as in: ``sizeof info`` after
-``struct fileinfo info;`` is declared).
-
-So use a space after these keywords::
-
-	if, switch, case, for, do, while
-
-but not with sizeof, typeof, alignof, or __attribute__.  E.g.,
-
-.. code-block:: c
-
-
-	s = sizeof(struct file);
-
-Do not add spaces around (inside) parenthesized expressions.  This example is
-**bad**:
-
-.. code-block:: c
-
-
-	s = sizeof( struct file );
-
-When declaring pointer data or a function that returns a pointer type, the
-preferred use of ``*`` is adjacent to the data name or function name and not
-adjacent to the type name.  Examples:
-
-.. code-block:: c
-
-
-	char *linux_banner;
-	unsigned long long memparse(char *ptr, char **retptr);
-	char *match_strdup(substring_t *s);
-
-Use one space around (on each side of) most binary and ternary operators,
-such as any of these::
-
-	=  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :
-
-but no space after unary operators::
-
-	&  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined
-
-no space before the postfix increment & decrement unary operators::
-
-	++  --
-
-no space after the prefix increment & decrement unary operators::
-
-	++  --
-
-and no space around the ``.`` and ``->`` structure member operators.
-
-Do not leave trailing whitespace at the ends of lines.  Some editors with
-``smart`` indentation will insert whitespace at the beginning of new lines as
-appropriate, so you can start typing the next line of code right away.
-However, some such editors do not remove the whitespace if you end up not
-putting a line of code there, such as if you leave a blank line.  As a result,
-you end up with lines containing trailing whitespace.
-
-Git will warn you about patches that introduce trailing whitespace, and can
-optionally strip the trailing whitespace for you; however, if applying a series
-of patches, this may make later patches in the series fail by changing their
-context lines.
-
-
-4) Naming
----------
-
-C is a Spartan language, and so should your naming be.  Unlike Modula-2
-and Pascal programmers, C programmers do not use cute names like
-ThisVariableIsATemporaryCounter.  A C programmer would call that
-variable ``tmp``, which is much easier to write, and not the least more
-difficult to understand.
-
-HOWEVER, while mixed-case names are frowned upon, descriptive names for
-global variables are a must.  To call a global function ``foo`` is a
-shooting offense.
-
-GLOBAL variables (to be used only if you **really** need them) need to
-have descriptive names, as do global functions.  If you have a function
-that counts the number of active users, you should call that
-``count_active_users()`` or similar, you should **not** call it ``cntusr()``.
-
-Encoding the type of a function into the name (so-called Hungarian
-notation) is brain damaged - the compiler knows the types anyway and can
-check those, and it only confuses the programmer.  No wonder MicroSoft
-makes buggy programs.
-
-LOCAL variable names should be short, and to the point.  If you have
-some random integer loop counter, it should probably be called ``i``.
-Calling it ``loop_counter`` is non-productive, if there is no chance of it
-being mis-understood.  Similarly, ``tmp`` can be just about any type of
-variable that is used to hold a temporary value.
-
-If you are afraid to mix up your local variable names, you have another
-problem, which is called the function-growth-hormone-imbalance syndrome.
-See chapter 6 (Functions).
-
-
-5) Typedefs
------------
-
-Please don't use things like ``vps_t``.
-It's a **mistake** to use typedef for structures and pointers. When you see a
-
-.. code-block:: c
-
-
-	vps_t a;
-
-in the source, what does it mean?
-In contrast, if it says
-
-.. code-block:: c
-
-	struct virtual_container *a;
-
-you can actually tell what ``a`` is.
-
-Lots of people think that typedefs ``help readability``. Not so. They are
-useful only for:
-
- (a) totally opaque objects (where the typedef is actively used to **hide**
-     what the object is).
-
-     Example: ``pte_t`` etc. opaque objects that you can only access using
-     the proper accessor functions.
-
-     .. note::
-
-       Opaqueness and ``accessor functions`` are not good in themselves.
-       The reason we have them for things like pte_t etc. is that there
-       really is absolutely **zero** portably accessible information there.
-
- (b) Clear integer types, where the abstraction **helps** avoid confusion
-     whether it is ``int`` or ``long``.
-
-     u8/u16/u32 are perfectly fine typedefs, although they fit into
-     category (d) better than here.
-
-     .. note::
-
-       Again - there needs to be a **reason** for this. If something is
-       ``unsigned long``, then there's no reason to do
-
-	typedef unsigned long myflags_t;
-
-     but if there is a clear reason for why it under certain circumstances
-     might be an ``unsigned int`` and under other configurations might be
-     ``unsigned long``, then by all means go ahead and use a typedef.
-
- (c) when you use sparse to literally create a **new** type for
-     type-checking.
-
- (d) New types which are identical to standard C99 types, in certain
-     exceptional circumstances.
-
-     Although it would only take a short amount of time for the eyes and
-     brain to become accustomed to the standard types like ``uint32_t``,
-     some people object to their use anyway.
-
-     Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
-     signed equivalents which are identical to standard types are
-     permitted -- although they are not mandatory in new code of your
-     own.
-
-     When editing existing code which already uses one or the other set
-     of types, you should conform to the existing choices in that code.
-
- (e) Types safe for use in userspace.
-
-     In certain structures which are visible to userspace, we cannot
-     require C99 types and cannot use the ``u32`` form above. Thus, we
-     use __u32 and similar types in all structures which are shared
-     with userspace.
-
-Maybe there are other cases too, but the rule should basically be to NEVER
-EVER use a typedef unless you can clearly match one of those rules.
-
-In general, a pointer, or a struct that has elements that can reasonably
-be directly accessed should **never** be a typedef.
-
-
-6) Functions
-------------
-
-Functions should be short and sweet, and do just one thing.  They should
-fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
-as we all know), and do one thing and do that well.
-
-The maximum length of a function is inversely proportional to the
-complexity and indentation level of that function.  So, if you have a
-conceptually simple function that is just one long (but simple)
-case-statement, where you have to do lots of small things for a lot of
-different cases, it's OK to have a longer function.
-
-However, if you have a complex function, and you suspect that a
-less-than-gifted first-year high-school student might not even
-understand what the function is all about, you should adhere to the
-maximum limits all the more closely.  Use helper functions with
-descriptive names (you can ask the compiler to in-line them if you think
-it's performance-critical, and it will probably do a better job of it
-than you would have done).
-
-Another measure of the function is the number of local variables.  They
-shouldn't exceed 5-10, or you're doing something wrong.  Re-think the
-function, and split it into smaller pieces.  A human brain can
-generally easily keep track of about 7 different things, anything more
-and it gets confused.  You know you're brilliant, but maybe you'd like
-to understand what you did 2 weeks from now.
-
-In source files, separate functions with one blank line.  If the function is
-exported, the **EXPORT** macro for it should follow immediately after the
-closing function brace line.  E.g.:
-
-.. code-block:: c
-
-	int system_is_up(void)
-	{
-		return system_state == SYSTEM_RUNNING;
-	}
-	EXPORT_SYMBOL(system_is_up);
-
-In function prototypes, include parameter names with their data types.
-Although this is not required by the C language, it is preferred in Linux
-because it is a simple way to add valuable information for the reader.
-
-
-7) Centralized exiting of functions
------------------------------------
-
-Albeit deprecated by some people, the equivalent of the goto statement is
-used frequently by compilers in form of the unconditional jump instruction.
-
-The goto statement comes in handy when a function exits from multiple
-locations and some common work such as cleanup has to be done.  If there is no
-cleanup needed then just return directly.
-
-Choose label names which say what the goto does or why the goto exists.  An
-example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``.
-Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to
-renumber them if you ever add or remove exit paths, and they make correctness
-difficult to verify anyway.
-
-The rationale for using gotos is:
-
-- unconditional statements are easier to understand and follow
-- nesting is reduced
-- errors by not updating individual exit points when making
-  modifications are prevented
-- saves the compiler work to optimize redundant code away ;)
-
-.. code-block:: c
-
-	int fun(int a)
-	{
-		int result = 0;
-		char *buffer;
-
-		buffer = kmalloc(SIZE, GFP_KERNEL);
-		if (!buffer)
-			return -ENOMEM;
-
-		if (condition1) {
-			while (loop1) {
-				...
-			}
-			result = 1;
-			goto out_buffer;
-		}
-		...
-	out_free_buffer:
-		kfree(buffer);
-		return result;
-	}
-
-A common type of bug to be aware of is ``one err bugs`` which look like this:
-
-.. code-block:: c
-
-	err:
-		kfree(foo->bar);
-		kfree(foo);
-		return ret;
-
-The bug in this code is that on some exit paths ``foo`` is NULL.  Normally the
-fix for this is to split it up into two error labels ``err_free_bar:`` and
-``err_free_foo:``:
-
-.. code-block:: c
-
-	 err_free_bar:
-		kfree(foo->bar);
-	 err_free_foo:
-		kfree(foo);
-		return ret;
-
-Ideally you should simulate errors to test all exit paths.
-
-
-8) Commenting
--------------
-
-Comments are good, but there is also a danger of over-commenting.  NEVER
-try to explain HOW your code works in a comment: it's much better to
-write the code so that the **working** is obvious, and it's a waste of
-time to explain badly written code.
-
-Generally, you want your comments to tell WHAT your code does, not HOW.
-Also, try to avoid putting comments inside a function body: if the
-function is so complex that you need to separately comment parts of it,
-you should probably go back to chapter 6 for a while.  You can make
-small comments to note or warn about something particularly clever (or
-ugly), but try to avoid excess.  Instead, put the comments at the head
-of the function, telling people what it does, and possibly WHY it does
-it.
-
-When commenting the kernel API functions, please use the kernel-doc format.
-See the files Documentation/kernel-documentation.rst and scripts/kernel-doc
-for details.
-
-The preferred style for long (multi-line) comments is:
-
-.. code-block:: c
-
-	/*
-	 * This is the preferred style for multi-line
-	 * comments in the Linux kernel source code.
-	 * Please use it consistently.
-	 *
-	 * Description:  A column of asterisks on the left side,
-	 * with beginning and ending almost-blank lines.
-	 */
-
-For files in net/ and drivers/net/ the preferred style for long (multi-line)
-comments is a little different.
-
-.. code-block:: c
-
-	/* The preferred comment style for files in net/ and drivers/net
-	 * looks like this.
-	 *
-	 * It is nearly the same as the generally preferred comment style,
-	 * but there is no initial almost-blank line.
-	 */
-
-It's also important to comment data, whether they are basic types or derived
-types.  To this end, use just one data declaration per line (no commas for
-multiple data declarations).  This leaves you room for a small comment on each
-item, explaining its use.
-
-
-9) You've made a mess of it
----------------------------
-
-That's OK, we all do.  You've probably been told by your long-time Unix
-user helper that ``GNU emacs`` automatically formats the C sources for
-you, and you've noticed that yes, it does do that, but the defaults it
-uses are less than desirable (in fact, they are worse than random
-typing - an infinite number of monkeys typing into GNU emacs would never
-make a good program).
-
-So, you can either get rid of GNU emacs, or change it to use saner
-values.  To do the latter, you can stick the following in your .emacs file:
-
-.. code-block:: none
-
-  (defun c-lineup-arglist-tabs-only (ignored)
-    "Line up argument lists by tabs, not spaces"
-    (let* ((anchor (c-langelem-pos c-syntactic-element))
-           (column (c-langelem-2nd-pos c-syntactic-element))
-           (offset (- (1+ column) anchor))
-           (steps (floor offset c-basic-offset)))
-      (* (max steps 1)
-         c-basic-offset)))
-
-  (add-hook 'c-mode-common-hook
-            (lambda ()
-              ;; Add kernel style
-              (c-add-style
-               "linux-tabs-only"
-               '("linux" (c-offsets-alist
-                          (arglist-cont-nonempty
-                           c-lineup-gcc-asm-reg
-                           c-lineup-arglist-tabs-only))))))
-
-  (add-hook 'c-mode-hook
-            (lambda ()
-              (let ((filename (buffer-file-name)))
-                ;; Enable kernel mode for the appropriate files
-                (when (and filename
-                           (string-match (expand-file-name "~/src/linux-trees")
-                                         filename))
-                  (setq indent-tabs-mode t)
-                  (setq show-trailing-whitespace t)
-                  (c-set-style "linux-tabs-only")))))
-
-This will make emacs go better with the kernel coding style for C
-files below ``~/src/linux-trees``.
-
-But even if you fail in getting emacs to do sane formatting, not
-everything is lost: use ``indent``.
-
-Now, again, GNU indent has the same brain-dead settings that GNU emacs
-has, which is why you need to give it a few command line options.
-However, that's not too bad, because even the makers of GNU indent
-recognize the authority of K&R (the GNU people aren't evil, they are
-just severely misguided in this matter), so you just give indent the
-options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
-``scripts/Lindent``, which indents in the latest style.
-
-``indent`` has a lot of options, and especially when it comes to comment
-re-formatting you may want to take a look at the man page.  But
-remember: ``indent`` is not a fix for bad programming.
-
-
-10) Kconfig configuration files
--------------------------------
-
-For all of the Kconfig* configuration files throughout the source tree,
-the indentation is somewhat different.  Lines under a ``config`` definition
-are indented with one tab, while help text is indented an additional two
-spaces.  Example::
-
-  config AUDIT
-	bool "Auditing support"
-	depends on NET
-	help
-	  Enable auditing infrastructure that can be used with another
-	  kernel subsystem, such as SELinux (which requires this for
-	  logging of avc messages output).  Does not do system-call
-	  auditing without CONFIG_AUDITSYSCALL.
-
-Seriously dangerous features (such as write support for certain
-filesystems) should advertise this prominently in their prompt string::
-
-  config ADFS_FS_RW
-	bool "ADFS write support (DANGEROUS)"
-	depends on ADFS_FS
-	...
-
-For full documentation on the configuration files, see the file
-Documentation/kbuild/kconfig-language.txt.
-
-
-11) Data structures
--------------------
-
-Data structures that have visibility outside the single-threaded
-environment they are created and destroyed in should always have
-reference counts.  In the kernel, garbage collection doesn't exist (and
-outside the kernel garbage collection is slow and inefficient), which
-means that you absolutely **have** to reference count all your uses.
-
-Reference counting means that you can avoid locking, and allows multiple
-users to have access to the data structure in parallel - and not having
-to worry about the structure suddenly going away from under them just
-because they slept or did something else for a while.
-
-Note that locking is **not** a replacement for reference counting.
-Locking is used to keep data structures coherent, while reference
-counting is a memory management technique.  Usually both are needed, and
-they are not to be confused with each other.
-
-Many data structures can indeed have two levels of reference counting,
-when there are users of different ``classes``.  The subclass count counts
-the number of subclass users, and decrements the global count just once
-when the subclass count goes to zero.
-
-Examples of this kind of ``multi-level-reference-counting`` can be found in
-memory management (``struct mm_struct``: mm_users and mm_count), and in
-filesystem code (``struct super_block``: s_count and s_active).
-
-Remember: if another thread can find your data structure, and you don't
-have a reference count on it, you almost certainly have a bug.
-
-
-12) Macros, Enums and RTL
--------------------------
-
-Names of macros defining constants and labels in enums are capitalized.
-
-.. code-block:: c
-
-	#define CONSTANT 0x12345
-
-Enums are preferred when defining several related constants.
-
-CAPITALIZED macro names are appreciated but macros resembling functions
-may be named in lower case.
-
-Generally, inline functions are preferable to macros resembling functions.
-
-Macros with multiple statements should be enclosed in a do - while block:
-
-.. code-block:: c
-
-	#define macrofun(a, b, c)			\
-		do {					\
-			if (a == 5)			\
-				do_this(b, c);		\
-		} while (0)
-
-Things to avoid when using macros:
-
-1) macros that affect control flow:
-
-.. code-block:: c
-
-	#define FOO(x)					\
-		do {					\
-			if (blah(x) < 0)		\
-				return -EBUGGERED;	\
-		} while (0)
-
-is a **very** bad idea.  It looks like a function call but exits the ``calling``
-function; don't break the internal parsers of those who will read the code.
-
-2) macros that depend on having a local variable with a magic name:
-
-.. code-block:: c
-
-	#define FOO(val) bar(index, val)
-
-might look like a good thing, but it's confusing as hell when one reads the
-code and it's prone to breakage from seemingly innocent changes.
-
-3) macros with arguments that are used as l-values: FOO(x) = y; will
-bite you if somebody e.g. turns FOO into an inline function.
-
-4) forgetting about precedence: macros defining constants using expressions
-must enclose the expression in parentheses. Beware of similar issues with
-macros using parameters.
-
-.. code-block:: c
-
-	#define CONSTANT 0x4000
-	#define CONSTEXP (CONSTANT | 3)
-
-5) namespace collisions when defining local variables in macros resembling
-functions:
-
-.. code-block:: c
-
-	#define FOO(x)				\
-	({					\
-		typeof(x) ret;			\
-		ret = calc_ret(x);		\
-		(ret);				\
-	})
-
-ret is a common name for a local variable - __foo_ret is less likely
-to collide with an existing variable.
-
-The cpp manual deals with macros exhaustively. The gcc internals manual also
-covers RTL which is used frequently with assembly language in the kernel.
-
-
-13) Printing kernel messages
-----------------------------
-
-Kernel developers like to be seen as literate. Do mind the spelling
-of kernel messages to make a good impression. Do not use crippled
-words like ``dont``; use ``do not`` or ``don't`` instead.  Make the messages
-concise, clear, and unambiguous.
-
-Kernel messages do not have to be terminated with a period.
-
-Printing numbers in parentheses (%d) adds no value and should be avoided.
-
-There are a number of driver model diagnostic macros in <linux/device.h>
-which you should use to make sure messages are matched to the right device
-and driver, and are tagged with the right level:  dev_err(), dev_warn(),
-dev_info(), and so forth.  For messages that aren't associated with a
-particular device, <linux/printk.h> defines pr_notice(), pr_info(),
-pr_warn(), pr_err(), etc.
-
-Coming up with good debugging messages can be quite a challenge; and once
-you have them, they can be a huge help for remote troubleshooting.  However
-debug message printing is handled differently than printing other non-debug
-messages.  While the other pr_XXX() functions print unconditionally,
-pr_debug() does not; it is compiled out by default, unless either DEBUG is
-defined or CONFIG_DYNAMIC_DEBUG is set.  That is true for dev_dbg() also,
-and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to
-the ones already enabled by DEBUG.
-
-Many subsystems have Kconfig debug options to turn on -DDEBUG in the
-corresponding Makefile; in other cases specific files #define DEBUG.  And
-when a debug message should be unconditionally printed, such as if it is
-already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
-used.
-
-
-14) Allocating memory
----------------------
-
-The kernel provides the following general purpose memory allocators:
-kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
-vzalloc().  Please refer to the API documentation for further information
-about them.
-
-The preferred form for passing a size of a struct is the following:
-
-.. code-block:: c
-
-	p = kmalloc(sizeof(*p), ...);
-
-The alternative form where struct name is spelled out hurts readability and
-introduces an opportunity for a bug when the pointer variable type is changed
-but the corresponding sizeof that is passed to a memory allocator is not.
-
-Casting the return value which is a void pointer is redundant. The conversion
-from void pointer to any other pointer type is guaranteed by the C programming
-language.
-
-The preferred form for allocating an array is the following:
-
-.. code-block:: c
-
-	p = kmalloc_array(n, sizeof(...), ...);
-
-The preferred form for allocating a zeroed array is the following:
-
-.. code-block:: c
-
-	p = kcalloc(n, sizeof(...), ...);
-
-Both forms check for overflow on the allocation size n * sizeof(...),
-and return NULL if that occurred.
-
-
-15) The inline disease
-----------------------
-
-There appears to be a common misperception that gcc has a magic "make me
-faster" speedup option called ``inline``. While the use of inlines can be
-appropriate (for example as a means of replacing macros, see Chapter 12), it
-very often is not. Abundant use of the inline keyword leads to a much bigger
-kernel, which in turn slows the system as a whole down, due to a bigger
-icache footprint for the CPU and simply because there is less memory
-available for the pagecache. Just think about it; a pagecache miss causes a
-disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles
-that can go into these 5 milliseconds.
-
-A reasonable rule of thumb is to not put inline at functions that have more
-than 3 lines of code in them. An exception to this rule are the cases where
-a parameter is known to be a compiletime constant, and as a result of this
-constantness you *know* the compiler will be able to optimize most of your
-function away at compile time. For a good example of this later case, see
-the kmalloc() inline function.
-
-Often people argue that adding inline to functions that are static and used
-only once is always a win since there is no space tradeoff. While this is
-technically correct, gcc is capable of inlining these automatically without
-help, and the maintenance issue of removing the inline when a second user
-appears outweighs the potential value of the hint that tells gcc to do
-something it would have done anyway.
-
-
-16) Function return values and names
-------------------------------------
-
-Functions can return values of many different kinds, and one of the
-most common is a value indicating whether the function succeeded or
-failed.  Such a value can be represented as an error-code integer
-(-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
-non-zero = success).
-
-Mixing up these two sorts of representations is a fertile source of
-difficult-to-find bugs.  If the C language included a strong distinction
-between integers and booleans then the compiler would find these mistakes
-for us... but it doesn't.  To help prevent such bugs, always follow this
-convention::
-
-	If the name of a function is an action or an imperative command,
-	the function should return an error-code integer.  If the name
-	is a predicate, the function should return a "succeeded" boolean.
-
-For example, ``add work`` is a command, and the add_work() function returns 0
-for success or -EBUSY for failure.  In the same way, ``PCI device present`` is
-a predicate, and the pci_dev_present() function returns 1 if it succeeds in
-finding a matching device or 0 if it doesn't.
-
-All EXPORTed functions must respect this convention, and so should all
-public functions.  Private (static) functions need not, but it is
-recommended that they do.
-
-Functions whose return value is the actual result of a computation, rather
-than an indication of whether the computation succeeded, are not subject to
-this rule.  Generally they indicate failure by returning some out-of-range
-result.  Typical examples would be functions that return pointers; they use
-NULL or the ERR_PTR mechanism to report failure.
-
-
-17) Don't re-invent the kernel macros
--------------------------------------
-
-The header file include/linux/kernel.h contains a number of macros that
-you should use, rather than explicitly coding some variant of them yourself.
-For example, if you need to calculate the length of an array, take advantage
-of the macro
-
-.. code-block:: c
-
-	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
-
-Similarly, if you need to calculate the size of some structure member, use
-
-.. code-block:: c
-
-	#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
-
-There are also min() and max() macros that do strict type checking if you
-need them.  Feel free to peruse that header file to see what else is already
-defined that you shouldn't reproduce in your code.
-
-
-18) Editor modelines and other cruft
-------------------------------------
-
-Some editors can interpret configuration information embedded in source files,
-indicated with special markers.  For example, emacs interprets lines marked
-like this:
-
-.. code-block:: c
-
-	-*- mode: c -*-
-
-Or like this:
-
-.. code-block:: c
-
-	/*
-	Local Variables:
-	compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
-	End:
-	*/
-
-Vim interprets markers that look like this:
-
-.. code-block:: c
-
-	/* vim:set sw=8 noet */
-
-Do not include any of these in source files.  People have their own personal
-editor configurations, and your source files should not override them.  This
-includes markers for indentation and mode configuration.  People may use their
-own custom mode, or may have some other magic method for making indentation
-work correctly.
-
-
-19) Inline assembly
--------------------
-
-In architecture-specific code, you may need to use inline assembly to interface
-with CPU or platform functionality.  Don't hesitate to do so when necessary.
-However, don't use inline assembly gratuitously when C can do the job.  You can
-and should poke hardware from C when possible.
-
-Consider writing simple helper functions that wrap common bits of inline
-assembly, rather than repeatedly writing them with slight variations.  Remember
-that inline assembly can use C parameters.
-
-Large, non-trivial assembly functions should go in .S files, with corresponding
-C prototypes defined in C header files.  The C prototypes for assembly
-functions should use ``asmlinkage``.
-
-You may need to mark your asm statement as volatile, to prevent GCC from
-removing it if GCC doesn't notice any side effects.  You don't always need to
-do so, though, and doing so unnecessarily can limit optimization.
-
-When writing a single inline assembly statement containing multiple
-instructions, put each instruction on a separate line in a separate quoted
-string, and end each string except the last with \n\t to properly indent the
-next instruction in the assembly output:
-
-.. code-block:: c
-
-	asm ("magic %reg1, #42\n\t"
-	     "more_magic %reg2, %reg3"
-	     : /* outputs */ : /* inputs */ : /* clobbers */);
-
-
-20) Conditional Compilation
----------------------------
-
-Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
-files; doing so makes code harder to read and logic harder to follow.  Instead,
-use such conditionals in a header file defining functions for use in those .c
-files, providing no-op stub versions in the #else case, and then call those
-functions unconditionally from .c files.  The compiler will avoid generating
-any code for the stub calls, producing identical results, but the logic will
-remain easy to follow.
-
-Prefer to compile out entire functions, rather than portions of functions or
-portions of expressions.  Rather than putting an ifdef in an expression, factor
-out part or all of the expression into a separate helper function and apply the
-conditional to that function.
-
-If you have a function or variable which may potentially go unused in a
-particular configuration, and the compiler would warn about its definition
-going unused, mark the definition as __maybe_unused rather than wrapping it in
-a preprocessor conditional.  (However, if a function or variable *always* goes
-unused, delete it.)
-
-Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
-symbol into a C boolean expression, and use it in a normal C conditional:
-
-.. code-block:: c
-
-	if (IS_ENABLED(CONFIG_SOMETHING)) {
-		...
-	}
-
-The compiler will constant-fold the conditional away, and include or exclude
-the block of code just as with an #ifdef, so this will not add any runtime
-overhead.  However, this approach still allows the C compiler to see the code
-inside the block, and check it for correctness (syntax, types, symbol
-references, etc).  Thus, you still have to use an #ifdef if the code inside the
-block references symbols that will not exist if the condition is not met.
-
-At the end of any non-trivial #if or #ifdef block (more than a few lines),
-place a comment after the #endif on the same line, noting the conditional
-expression used.  For instance:
-
-.. code-block:: c
-
-	#ifdef CONFIG_SOMETHING
-	...
-	#endif /* CONFIG_SOMETHING */
-
-
-Appendix I) References
-----------------------
-
-The C Programming Language, Second Edition
-by Brian W. Kernighan and Dennis M. Ritchie.
-Prentice Hall, Inc., 1988.
-ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
-
-The Practice of Programming
-by Brian W. Kernighan and Rob Pike.
-Addison-Wesley, Inc., 1999.
-ISBN 0-201-61586-X.
-
-GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
-gcc internals and indent, all available from http://www.gnu.org/manual/
-
-WG14 is the international standardization working group for the programming
-language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
-
-Kernel CodingStyle, by greg@kroah.com at OLS 2002:
-http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
+This file has moved to process/coding-style.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index fdf8232..caab903 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -9,12 +9,10 @@
 DOCBOOKS := z8530book.xml  \
 	    kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
 	    writing_usb_driver.xml networking.xml \
-	    kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
+	    kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
 	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
-	    debugobjects.xml sh.xml regulator.xml \
-	    alsa-driver-api.xml writing-an-alsa-driver.xml \
-	    tracepoint.xml w1.xml \
+	    80211.xml sh.xml regulator.xml w1.xml \
 	    writing_musb_glue_layer.xml crypto-API.xml iio.xml
 
 ifeq ($(DOCBOOKS),)
@@ -264,6 +262,7 @@
 	$(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
 	$(patsubst %.xml, %.xml.db,  $(DOCBOOKS)) \
 	$(patsubst %.xml, %.xml,     $(DOCBOOKS)) \
+	$(patsubst %.xml, .%.xml.cmd, $(DOCBOOKS)) \
 	$(index)
 
 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
diff --git a/Documentation/DocBook/alsa-driver-api.tmpl b/Documentation/DocBook/alsa-driver-api.tmpl
deleted file mode 100644
index 53f439d..0000000
--- a/Documentation/DocBook/alsa-driver-api.tmpl
+++ /dev/null
@@ -1,142 +0,0 @@
-<?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" []>
-
-<!-- ****************************************************** -->
-<!-- Header  -->
-<!-- ****************************************************** -->
-<book id="ALSA-Driver-API">
-  <bookinfo>
-    <title>The ALSA Driver API</title>
-
-    <legalnotice>
-    <para>
-    This document is free; 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 document is distributed in the hope that it will be useful,
-    but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the
-    implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A
-    PARTICULAR PURPOSE</emphasis>. 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>
-    </legalnotice>
-
-  </bookinfo>
-
-<toc></toc>
-
-  <chapter><title>Management of Cards and Devices</title>
-     <sect1><title>Card Management</title>
-!Esound/core/init.c
-     </sect1>
-     <sect1><title>Device Components</title>
-!Esound/core/device.c
-     </sect1>
-     <sect1><title>Module requests and Device File Entries</title>
-!Esound/core/sound.c
-     </sect1>
-     <sect1><title>Memory Management Helpers</title>
-!Esound/core/memory.c
-!Esound/core/memalloc.c
-     </sect1>
-  </chapter>
-  <chapter><title>PCM API</title>
-     <sect1><title>PCM Core</title>
-!Esound/core/pcm.c
-!Esound/core/pcm_lib.c
-!Esound/core/pcm_native.c
-!Iinclude/sound/pcm.h
-     </sect1>
-     <sect1><title>PCM Format Helpers</title>
-!Esound/core/pcm_misc.c
-     </sect1>
-     <sect1><title>PCM Memory Management</title>
-!Esound/core/pcm_memory.c
-     </sect1>
-     <sect1><title>PCM DMA Engine API</title>
-!Esound/core/pcm_dmaengine.c
-!Iinclude/sound/dmaengine_pcm.h
-     </sect1>
-  </chapter>
-  <chapter><title>Control/Mixer API</title>
-     <sect1><title>General Control Interface</title>
-!Esound/core/control.c
-     </sect1>
-     <sect1><title>AC97 Codec API</title>
-!Esound/pci/ac97/ac97_codec.c
-!Esound/pci/ac97/ac97_pcm.c
-     </sect1>
-     <sect1><title>Virtual Master Control API</title>
-!Esound/core/vmaster.c
-!Iinclude/sound/control.h
-     </sect1>
-  </chapter>
-  <chapter><title>MIDI API</title>
-     <sect1><title>Raw MIDI API</title>
-!Esound/core/rawmidi.c
-     </sect1>
-     <sect1><title>MPU401-UART API</title>
-!Esound/drivers/mpu401/mpu401_uart.c
-     </sect1>
-  </chapter>
-  <chapter><title>Proc Info API</title>
-     <sect1><title>Proc Info Interface</title>
-!Esound/core/info.c
-     </sect1>
-  </chapter>
-  <chapter><title>Compress Offload</title>
-     <sect1><title>Compress Offload API</title>
-!Esound/core/compress_offload.c
-!Iinclude/uapi/sound/compress_offload.h
-!Iinclude/uapi/sound/compress_params.h
-!Iinclude/sound/compress_driver.h
-     </sect1>
-  </chapter>
-  <chapter><title>ASoC</title>
-     <sect1><title>ASoC Core API</title>
-!Iinclude/sound/soc.h
-!Esound/soc/soc-core.c
-<!-- !Esound/soc/soc-cache.c no docbook comments here -->
-!Esound/soc/soc-devres.c
-!Esound/soc/soc-io.c
-!Esound/soc/soc-pcm.c
-!Esound/soc/soc-ops.c
-!Esound/soc/soc-compress.c
-     </sect1>
-     <sect1><title>ASoC DAPM API</title>
-!Esound/soc/soc-dapm.c
-     </sect1>
-     <sect1><title>ASoC DMA Engine API</title>
-!Esound/soc/soc-generic-dmaengine-pcm.c
-     </sect1>
-  </chapter>
-  <chapter><title>Miscellaneous Functions</title>
-     <sect1><title>Hardware-Dependent Devices API</title>
-!Esound/core/hwdep.c
-     </sect1>
-     <sect1><title>Jack Abstraction Layer API</title>
-!Iinclude/sound/jack.h
-!Esound/core/jack.c
-!Esound/soc/soc-jack.c
-     </sect1>
-     <sect1><title>ISA DMA Helpers</title>
-!Esound/core/isadma.c
-     </sect1>
-     <sect1><title>Other Helper Macros</title>
-!Iinclude/sound/core.h
-     </sect1>
-  </chapter>
-
-</book>
diff --git a/Documentation/DocBook/debugobjects.tmpl b/Documentation/DocBook/debugobjects.tmpl
deleted file mode 100644
index 7e4f34f..0000000
--- a/Documentation/DocBook/debugobjects.tmpl
+++ /dev/null
@@ -1,443 +0,0 @@
-<?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="debug-objects-guide">
- <bookinfo>
-  <title>Debug objects life time</title>
-
-  <authorgroup>
-   <author>
-    <firstname>Thomas</firstname>
-    <surname>Gleixner</surname>
-    <affiliation>
-     <address>
-      <email>tglx@linutronix.de</email>
-     </address>
-    </affiliation>
-   </author>
-  </authorgroup>
-
-  <copyright>
-   <year>2008</year>
-   <holder>Thomas Gleixner</holder>
-  </copyright>
-
-  <legalnotice>
-   <para>
-     This documentation is free software; you can redistribute
-     it and/or modify it under the terms of the GNU General Public
-     License version 2 as published by the Free Software Foundation.
-   </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="intro">
-    <title>Introduction</title>
-    <para>
-      debugobjects is a generic infrastructure to track the life time
-      of kernel objects and validate the operations on those.
-    </para>
-    <para>
-      debugobjects is useful to check for the following error patterns:
-	<itemizedlist>
-	  <listitem><para>Activation of uninitialized objects</para></listitem>
-	  <listitem><para>Initialization of active objects</para></listitem>
-	  <listitem><para>Usage of freed/destroyed objects</para></listitem>
-	</itemizedlist>
-    </para>
-    <para>
-      debugobjects is not changing the data structure of the real
-      object so it can be compiled in with a minimal runtime impact
-      and enabled on demand with a kernel command line option.
-    </para>
-  </chapter>
-
-  <chapter id="howto">
-    <title>Howto use debugobjects</title>
-    <para>
-      A kernel subsystem needs to provide a data structure which
-      describes the object type and add calls into the debug code at
-      appropriate places. The data structure to describe the object
-      type needs at minimum the name of the object type. Optional
-      functions can and should be provided to fixup detected problems
-      so the kernel can continue to work and the debug information can
-      be retrieved from a live system instead of hard core debugging
-      with serial consoles and stack trace transcripts from the
-      monitor.
-    </para>
-    <para>
-      The debug calls provided by debugobjects are:
-      <itemizedlist>
-	<listitem><para>debug_object_init</para></listitem>
-	<listitem><para>debug_object_init_on_stack</para></listitem>
-	<listitem><para>debug_object_activate</para></listitem>
-	<listitem><para>debug_object_deactivate</para></listitem>
-	<listitem><para>debug_object_destroy</para></listitem>
-	<listitem><para>debug_object_free</para></listitem>
-	<listitem><para>debug_object_assert_init</para></listitem>
-      </itemizedlist>
-      Each of these functions takes the address of the real object and
-      a pointer to the object type specific debug description
-      structure.
-    </para>
-    <para>
-      Each detected error is reported in the statistics and a limited
-      number of errors are printk'ed including a full stack trace.
-    </para>
-    <para>
-      The statistics are available via /sys/kernel/debug/debug_objects/stats.
-      They provide information about the number of warnings and the
-      number of successful fixups along with information about the
-      usage of the internal tracking objects and the state of the
-      internal tracking objects pool.
-    </para>
-  </chapter>
-  <chapter id="debugfunctions">
-    <title>Debug functions</title>
-    <sect1 id="prototypes">
-      <title>Debug object function reference</title>
-!Elib/debugobjects.c
-    </sect1>
-    <sect1 id="debug_object_init">
-      <title>debug_object_init</title>
-      <para>
-	This function is called whenever the initialization function
-	of a real object is called.
-      </para>
-      <para>
-	When the real object is already tracked by debugobjects it is
-	checked, whether the object can be initialized.  Initializing
-	is not allowed for active and destroyed objects. When
-	debugobjects detects an error, then it calls the fixup_init
-	function of the object type description structure if provided
-	by the caller. The fixup function can correct the problem
-	before the real initialization of the object happens. E.g. it
-	can deactivate an active object in order to prevent damage to
-	the subsystem.
-      </para>
-      <para>
-	When the real object is not yet tracked by debugobjects,
-	debugobjects allocates a tracker object for the real object
-	and sets the tracker object state to ODEBUG_STATE_INIT. It
-	verifies that the object is not on the callers stack. If it is
-	on the callers stack then a limited number of warnings
-	including a full stack trace is printk'ed. The calling code
-	must use debug_object_init_on_stack() and remove the object
-	before leaving the function which allocated it. See next
-	section.
-      </para>
-    </sect1>
-
-    <sect1 id="debug_object_init_on_stack">
-      <title>debug_object_init_on_stack</title>
-      <para>
-	This function is called whenever the initialization function
-	of a real object which resides on the stack is called.
-      </para>
-      <para>
-	When the real object is already tracked by debugobjects it is
-	checked, whether the object can be initialized. Initializing
-	is not allowed for active and destroyed objects. When
-	debugobjects detects an error, then it calls the fixup_init
-	function of the object type description structure if provided
-	by the caller. The fixup function can correct the problem
-	before the real initialization of the object happens. E.g. it
-	can deactivate an active object in order to prevent damage to
-	the subsystem.
-      </para>
-      <para>
-	When the real object is not yet tracked by debugobjects
-	debugobjects allocates a tracker object for the real object
-	and sets the tracker object state to ODEBUG_STATE_INIT. It
-	verifies that the object is on the callers stack.
-      </para>
-      <para>
-	An object which is on the stack must be removed from the
-	tracker by calling debug_object_free() before the function
-	which allocates the object returns. Otherwise we keep track of
-	stale objects.
-      </para>
-    </sect1>
-
-    <sect1 id="debug_object_activate">
-      <title>debug_object_activate</title>
-      <para>
-	This function is called whenever the activation function of a
-	real object is called.
-      </para>
-      <para>
-	When the real object is already tracked by debugobjects it is
-	checked, whether the object can be activated.  Activating is
-	not allowed for active and destroyed objects. When
-	debugobjects detects an error, then it calls the
-	fixup_activate function of the object type description
-	structure if provided by the caller. The fixup function can
-	correct the problem before the real activation of the object
-	happens. E.g. it can deactivate an active object in order to
-	prevent damage to the subsystem.
-      </para>
-      <para>
-	When the real object is not yet tracked by debugobjects then
-	the fixup_activate function is called if available. This is
-	necessary to allow the legitimate activation of statically
-	allocated and initialized objects. The fixup function checks
-	whether the object is valid and calls the debug_objects_init()
-	function to initialize the tracking of this object.
-      </para>
-      <para>
-	When the activation is legitimate, then the state of the
-	associated tracker object is set to ODEBUG_STATE_ACTIVE.
-      </para>
-    </sect1>
-
-    <sect1 id="debug_object_deactivate">
-      <title>debug_object_deactivate</title>
-      <para>
-	This function is called whenever the deactivation function of
-	a real object is called.
-      </para>
-      <para>
-	When the real object is tracked by debugobjects it is checked,
-	whether the object can be deactivated. Deactivating is not
-	allowed for untracked or destroyed objects.
-      </para>
-      <para>
-	When the deactivation is legitimate, then the state of the
-	associated tracker object is set to ODEBUG_STATE_INACTIVE.
-      </para>
-    </sect1>
-
-    <sect1 id="debug_object_destroy">
-      <title>debug_object_destroy</title>
-      <para>
-	This function is called to mark an object destroyed. This is
-	useful to prevent the usage of invalid objects, which are
-	still available in memory: either statically allocated objects
-	or objects which are freed later.
-      </para>
-      <para>
-	When the real object is tracked by debugobjects it is checked,
-	whether the object can be destroyed. Destruction is not
-	allowed for active and destroyed objects. When debugobjects
-	detects an error, then it calls the fixup_destroy function of
-	the object type description structure if provided by the
-	caller. The fixup function can correct the problem before the
-	real destruction of the object happens. E.g. it can deactivate
-	an active object in order to prevent damage to the subsystem.
-      </para>
-      <para>
-	When the destruction is legitimate, then the state of the
-	associated tracker object is set to ODEBUG_STATE_DESTROYED.
-      </para>
-    </sect1>
-
-    <sect1 id="debug_object_free">
-      <title>debug_object_free</title>
-      <para>
-	This function is called before an object is freed.
-      </para>
-      <para>
-	When the real object is tracked by debugobjects it is checked,
-	whether the object can be freed. Free is not allowed for
-	active objects. When debugobjects detects an error, then it
-	calls the fixup_free function of the object type description
-	structure if provided by the caller. The fixup function can
-	correct the problem before the real free of the object
-	happens. E.g. it can deactivate an active object in order to
-	prevent damage to the subsystem.
-      </para>
-      <para>
-	Note that debug_object_free removes the object from the
-	tracker. Later usage of the object is detected by the other
-	debug checks.
-      </para>
-    </sect1>
-
-    <sect1 id="debug_object_assert_init">
-      <title>debug_object_assert_init</title>
-      <para>
-	This function is called to assert that an object has been
-	initialized.
-      </para>
-      <para>
-	When the real object is not tracked by debugobjects, it calls
-	fixup_assert_init of the object type description structure
-	provided by the caller, with the hardcoded object state
-	ODEBUG_NOT_AVAILABLE. The fixup function can correct the problem
-	by calling debug_object_init and other specific initializing
-	functions.
-      </para>
-      <para>
-	When the real object is already tracked by debugobjects it is
-	ignored.
-      </para>
-    </sect1>
-  </chapter>
-  <chapter id="fixupfunctions">
-    <title>Fixup functions</title>
-    <sect1 id="debug_obj_descr">
-      <title>Debug object type description structure</title>
-!Iinclude/linux/debugobjects.h
-    </sect1>
-    <sect1 id="fixup_init">
-      <title>fixup_init</title>
-      <para>
-	This function is called from the debug code whenever a problem
-	in debug_object_init is detected. The function takes the
-	address of the object and the state which is currently
-	recorded in the tracker.
-      </para>
-      <para>
-	Called from debug_object_init when the object state is:
-	<itemizedlist>
-	  <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
-	</itemizedlist>
-      </para>
-      <para>
-	The function returns true when the fixup was successful,
-	otherwise false. The return value is used to update the
-	statistics.
-      </para>
-      <para>
-	Note, that the function needs to call the debug_object_init()
-	function again, after the damage has been repaired in order to
-	keep the state consistent.
-      </para>
-    </sect1>
-
-    <sect1 id="fixup_activate">
-      <title>fixup_activate</title>
-      <para>
-	This function is called from the debug code whenever a problem
-	in debug_object_activate is detected.
-      </para>
-      <para>
-	Called from debug_object_activate when the object state is:
-	<itemizedlist>
-	  <listitem><para>ODEBUG_STATE_NOTAVAILABLE</para></listitem>
-	  <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
-	</itemizedlist>
-      </para>
-      <para>
-	The function returns true when the fixup was successful,
-	otherwise false. The return value is used to update the
-	statistics.
-      </para>
-      <para>
-	Note that the function needs to call the debug_object_activate()
-	function again after the damage has been repaired in order to
-	keep the state consistent.
-      </para>
-      <para>
-	The activation of statically initialized objects is a special
-	case. When debug_object_activate() has no tracked object for
-	this object address then fixup_activate() is called with
-	object state ODEBUG_STATE_NOTAVAILABLE. The fixup function
-	needs to check whether this is a legitimate case of a
-	statically initialized object or not. In case it is it calls
-	debug_object_init() and debug_object_activate() to make the
-	object known to the tracker and marked active. In this case
-	the function should return false because this is not a real
-	fixup.
-      </para>
-    </sect1>
-
-    <sect1 id="fixup_destroy">
-      <title>fixup_destroy</title>
-      <para>
-	This function is called from the debug code whenever a problem
-	in debug_object_destroy is detected.
-      </para>
-      <para>
-	Called from debug_object_destroy when the object state is:
-	<itemizedlist>
-	  <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
-	</itemizedlist>
-      </para>
-      <para>
-	The function returns true when the fixup was successful,
-	otherwise false. The return value is used to update the
-	statistics.
-      </para>
-    </sect1>
-    <sect1 id="fixup_free">
-      <title>fixup_free</title>
-      <para>
-	This function is called from the debug code whenever a problem
-	in debug_object_free is detected. Further it can be called
-	from the debug checks in kfree/vfree, when an active object is
-	detected from the debug_check_no_obj_freed() sanity checks.
-      </para>
-      <para>
-	Called from debug_object_free() or debug_check_no_obj_freed()
-	when the object state is:
-	<itemizedlist>
-	  <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
-	</itemizedlist>
-      </para>
-      <para>
-	The function returns true when the fixup was successful,
-	otherwise false. The return value is used to update the
-	statistics.
-      </para>
-    </sect1>
-    <sect1 id="fixup_assert_init">
-      <title>fixup_assert_init</title>
-      <para>
-	This function is called from the debug code whenever a problem
-	in debug_object_assert_init is detected.
-      </para>
-      <para>
-	Called from debug_object_assert_init() with a hardcoded state
-	ODEBUG_STATE_NOTAVAILABLE when the object is not found in the
-	debug bucket.
-      </para>
-      <para>
-	The function returns true when the fixup was successful,
-	otherwise false. The return value is used to update the
-	statistics.
-      </para>
-      <para>
-	Note, this function should make sure debug_object_init() is
-	called before returning.
-      </para>
-      <para>
-	The handling of statically initialized objects is a special
-	case. The fixup function should check if this is a legitimate
-	case of a statically initialized object or not. In this case only
-	debug_object_init() should be called to make the object known to
-	the tracker. Then the function should return false because this
-	is not
-	a real fixup.
-      </para>
-    </sect1>
-  </chapter>
-  <chapter id="bugs">
-    <title>Known Bugs And Assumptions</title>
-    <para>
-	None (knock on wood).
-    </para>
-  </chapter>
-</book>
diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl
index 2a27227..da5c087 100644
--- a/Documentation/DocBook/kernel-hacking.tmpl
+++ b/Documentation/DocBook/kernel-hacking.tmpl
@@ -1208,8 +1208,8 @@
    
    <listitem>
     <para>
-     Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename>
-     and possibly <filename>Documentation/SubmittingDrivers</filename>.
+     Finally, don't forget to read <filename>Documentation/process/submitting-patches.rst</filename>
+     and possibly <filename>Documentation/process/submitting-drivers.rst</filename>.
     </para>
    </listitem>
   </itemizedlist>
diff --git a/Documentation/DocBook/tracepoint.tmpl b/Documentation/DocBook/tracepoint.tmpl
deleted file mode 100644
index b57a9ed..0000000
--- a/Documentation/DocBook/tracepoint.tmpl
+++ /dev/null
@@ -1,112 +0,0 @@
-<?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="Tracepoints">
- <bookinfo>
-  <title>The Linux Kernel Tracepoint API</title>
-
-  <authorgroup>
-   <author>
-    <firstname>Jason</firstname>
-    <surname>Baron</surname>
-    <affiliation>
-     <address>
-      <email>jbaron@redhat.com</email>
-     </address>
-    </affiliation>
-   </author>
-   <author>
-    <firstname>William</firstname>
-    <surname>Cohen</surname>
-    <affiliation>
-     <address>
-      <email>wcohen@redhat.com</email>
-     </address>
-    </affiliation>
-   </author>
-  </authorgroup>
-
-  <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="intro">
-   <title>Introduction</title>
-   <para>
-     Tracepoints are static probe points that are located in strategic points
-     throughout the kernel. 'Probes' register/unregister with tracepoints
-     via a callback mechanism. The 'probes' are strictly typed functions that
-     are passed a unique set of parameters defined by each tracepoint.
-   </para>
-
-   <para>
-     From this simple callback mechanism, 'probes' can be used to profile, debug,
-     and understand kernel behavior. There are a number of tools that provide a
-     framework for using 'probes'. These tools include Systemtap, ftrace, and
-     LTTng.
-   </para>
-
-   <para>
-     Tracepoints are defined in a number of header files via various macros. Thus,
-     the purpose of this document is to provide a clear accounting of the available
-     tracepoints. The intention is to understand not only what tracepoints are
-     available but also to understand where future tracepoints might be added.
-   </para>
-
-   <para>
-     The API presented has functions of the form:
-     <function>trace_tracepointname(function parameters)</function>. These are the
-     tracepoints callbacks that are found throughout the code. Registering and
-     unregistering probes with these callback sites is covered in the
-     <filename>Documentation/trace/*</filename> directory.
-   </para>
-  </chapter>
-
-  <chapter id="irq">
-   <title>IRQ</title>
-!Iinclude/trace/events/irq.h
-  </chapter>
-
-  <chapter id="signal">
-   <title>SIGNAL</title>
-!Iinclude/trace/events/signal.h
-  </chapter>
-
-  <chapter id="block">
-   <title>Block IO</title>
-!Iinclude/trace/events/block.h
-  </chapter>
-
-  <chapter id="workqueue">
-   <title>Workqueue</title>
-!Iinclude/trace/events/workqueue.h
-  </chapter>
-</book>
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl
index cd0e452..5210f8a 100644
--- a/Documentation/DocBook/uio-howto.tmpl
+++ b/Documentation/DocBook/uio-howto.tmpl
@@ -46,6 +46,13 @@
 
 <revhistory>
 	<revision>
+	<revnumber>0.10</revnumber>
+	<date>2016-10-17</date>
+	<authorinitials>sch</authorinitials>
+	<revremark>Added generic hyperv driver
+		</revremark>
+	</revision>
+	<revision>
 	<revnumber>0.9</revnumber>
 	<date>2009-07-16</date>
 	<authorinitials>mst</authorinitials>
@@ -1033,6 +1040,61 @@
 
 </chapter>
 
+<chapter id="uio_hv_generic" xreflabel="Using Generic driver for Hyper-V VMBUS">
+<?dbhtml filename="uio_hv_generic.html"?>
+<title>Generic Hyper-V UIO driver</title>
+	<para>
+	The generic driver is a kernel module named uio_hv_generic.
+	It supports devices on the Hyper-V VMBus similar to uio_pci_generic
+	on PCI bus.
+	</para>
+
+<sect1 id="uio_hv_generic_binding">
+<title>Making the driver recognize the device</title>
+	<para>
+Since the driver does not declare any device GUID's, it will not get loaded
+automatically and will not automatically bind to any devices, you must load it
+and allocate id to the driver yourself. For example, to use the network device
+GUID:
+	<programlisting>
+ modprobe uio_hv_generic
+ echo &quot;f8615163-df3e-46c5-913f-f2d2f965ed0e&quot; &gt; /sys/bus/vmbus/drivers/uio_hv_generic/new_id
+	</programlisting>
+	</para>
+	<para>
+If there already is a hardware specific kernel driver for the device, the
+generic driver still won't bind to it, in this case if you want to use the
+generic driver (why would you?) you'll have to manually unbind the hardware
+specific driver and bind the generic driver, like this:
+	<programlisting>
+	  echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 &gt; /sys/bus/vmbus/drivers/hv_netvsc/unbind
+	  echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 &gt; /sys/bus/vmbus/drivers/uio_hv_generic/bind
+	</programlisting>
+	</para>
+	<para>
+You can verify that the device has been bound to the driver
+by looking for it in sysfs, for example like the following:
+	<programlisting>
+    ls -l /sys/bus/vmbus/devices/vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver
+	</programlisting>
+Which if successful should print
+	<programlisting>
+  .../vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -&gt; ../../../bus/vmbus/drivers/uio_hv_generic
+	</programlisting>
+	</para>
+</sect1>
+
+<sect1 id="uio_hv_generic_internals">
+<title>Things to know about uio_hv_generic</title>
+	<para>
+On each interrupt, uio_hv_generic sets the Interrupt Disable bit.
+This prevents the device from generating further interrupts
+until the bit is cleared. The userspace driver should clear this
+bit before blocking and waiting for more interrupts.
+	</para>
+</sect1>
+</chapter>
+
 <appendix id="app1">
 <title>Further information</title>
 <itemizedlist>
diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl
deleted file mode 100644
index bc776be0..0000000
--- a/Documentation/DocBook/usb.tmpl
+++ /dev/null
@@ -1,992 +0,0 @@
-<?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="Linux-USB-API">
- <bookinfo>
-  <title>The Linux-USB Host Side 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="intro">
-    <title>Introduction to USB on Linux</title>
-
-    <para>A Universal Serial Bus (USB) is used to connect a host,
-    such as a PC or workstation, to a number of peripheral
-    devices.  USB uses a tree structure, with the host as the
-    root (the system's master), hubs as interior nodes, and
-    peripherals as leaves (and slaves).
-    Modern PCs support several such trees of USB devices, usually
-    one USB 2.0 tree (480 Mbit/sec each) with
-    a few USB 1.1 trees (12 Mbit/sec each) that are used when you
-    connect a USB 1.1 device directly to the machine's "root hub".
-    </para>
-
-    <para>That master/slave asymmetry was designed-in for a number of
-    reasons, one being ease of use.  It is not physically possible to
-    assemble (legal) USB cables incorrectly:  all upstream "to the host"
-    connectors are the rectangular type (matching the sockets on
-    root hubs), and all downstream connectors are the squarish type
-    (or they are built into the peripheral).
-    Also, the host software doesn't need to deal with distributed
-    auto-configuration since the pre-designated master node manages all that.
-    And finally, at the electrical level, bus protocol overhead is reduced by
-    eliminating arbitration and moving scheduling into the host software.
-    </para>
-
-    <para>USB 1.0 was announced in January 1996 and was revised
-    as USB 1.1 (with improvements in hub specification and
-    support for interrupt-out transfers) in September 1998.
-    USB 2.0 was released in April 2000, adding high-speed
-    transfers and transaction-translating hubs (used for USB 1.1
-    and 1.0 backward compatibility).
-    </para>
-
-    <para>Kernel developers added USB support to Linux early in the 2.2 kernel
-    series, shortly before 2.3 development forked.  Updates from 2.3 were
-    regularly folded back into 2.2 releases, which improved reliability and
-    brought <filename>/sbin/hotplug</filename> support as well more drivers.
-    Such improvements were continued in the 2.5 kernel series, where they added
-    USB 2.0 support, improved performance, and made the host controller drivers
-    (HCDs) more consistent.  They also simplified the API (to make bugs less
-    likely) and added internal "kerneldoc" documentation.
-    </para>
-
-    <para>Linux can run inside USB devices as well as on
-    the hosts that control the devices.
-    But USB device drivers running inside those peripherals
-    don't do the same things as the ones running inside hosts,
-    so they've been given a different name:
-    <emphasis>gadget drivers</emphasis>.
-    This document does not cover gadget drivers.
-    </para>
-
-    </chapter>
-
-<chapter id="host">
-    <title>USB Host-Side API Model</title>
-
-    <para>Host-side drivers for USB devices talk to the "usbcore" APIs.
-    There are two.  One is intended for
-    <emphasis>general-purpose</emphasis> drivers (exposed through
-    driver frameworks), and the other is for drivers that are
-    <emphasis>part of the core</emphasis>.
-    Such core drivers include the <emphasis>hub</emphasis> driver
-    (which manages trees of USB devices) and several different kinds
-    of <emphasis>host controller drivers</emphasis>,
-    which control individual busses.
-    </para>
-
-    <para>The device model seen by USB drivers is relatively complex.
-    </para>
-     
-    <itemizedlist>
-
-	<listitem><para>USB supports four kinds of data transfers
-	(control, bulk, interrupt, and isochronous).  Two of them (control
-	and bulk) use bandwidth as it's available,
-	while the other two (interrupt and isochronous)
-	are scheduled to provide guaranteed bandwidth.
-	</para></listitem>
-
-	<listitem><para>The device description model includes one or more
-	"configurations" per device, only one of which is active at a time.
-	Devices that are capable of high-speed operation must also support
-	full-speed configurations, along with a way to ask about the
-	"other speed" configurations which might be used.
-	</para></listitem>
-
-	<listitem><para>Configurations have one or more "interfaces", each
-	of which may have "alternate settings".  Interfaces may be
-	standardized by USB "Class" specifications, or may be specific to
-	a vendor or device.</para>
-
-	<para>USB device drivers actually bind to interfaces, not devices.
-	Think of them as "interface drivers", though you
-	may not see many devices where the distinction is important.
-	<emphasis>Most USB devices are simple, with only one configuration,
-	one interface, and one alternate setting.</emphasis>
-	</para></listitem>
-
-	<listitem><para>Interfaces have one or more "endpoints", each of
-	which supports one type and direction of data transfer such as
-	"bulk out" or "interrupt in".  The entire configuration may have
-	up to sixteen endpoints in each direction, allocated as needed
-	among all the interfaces.
-	</para></listitem>
-
-	<listitem><para>Data transfer on USB is packetized; each endpoint
-	has a maximum packet size.
-	Drivers must often be aware of conventions such as flagging the end
-	of bulk transfers using "short" (including zero length) packets.
-	</para></listitem>
-
-	<listitem><para>The Linux USB API supports synchronous calls for
-	control and bulk messages.
-	It also supports asynchronous calls for all kinds of data transfer,
-	using request structures called "URBs" (USB Request Blocks).
-	</para></listitem>
-
-    </itemizedlist>
-
-    <para>Accordingly, the USB Core API exposed to device drivers
-    covers quite a lot of territory.  You'll probably need to consult
-    the USB 2.0 specification, available online from www.usb.org at
-    no cost, as well as class or device specifications.
-    </para>
-
-    <para>The only host-side drivers that actually touch hardware
-    (reading/writing registers, handling IRQs, and so on) are the HCDs.
-    In theory, all HCDs provide the same functionality through the same
-    API.  In practice, that's becoming more true on the 2.5 kernels,
-    but there are still differences that crop up especially with
-    fault handling.  Different controllers don't necessarily report
-    the same aspects of failures, and recovery from faults (including
-    software-induced ones like unlinking an URB) isn't yet fully
-    consistent.
-    Device driver authors should make a point of doing disconnect
-    testing (while the device is active) with each different host
-    controller driver, to make sure drivers don't have bugs of
-    their own as well as to make sure they aren't relying on some
-    HCD-specific behavior.
-    (You will need external USB 1.1 and/or
-    USB 2.0 hubs to perform all those tests.)
-    </para>
-
-    </chapter>
-
-<chapter id="types"><title>USB-Standard Types</title>
-
-    <para>In <filename>&lt;linux/usb/ch9.h&gt;</filename> you will find
-    the USB data types defined in chapter 9 of the USB specification.
-    These data types are used throughout USB, and in APIs including
-    this host side API, gadget APIs, and usbfs.
-    </para>
-
-!Iinclude/linux/usb/ch9.h
-
-    </chapter>
-
-<chapter id="hostside"><title>Host-Side Data Types and Macros</title>
-
-    <para>The host side API exposes several layers to drivers, some of
-    which are more necessary than others.
-    These support lifecycle models for host side drivers
-    and devices, and support passing buffers through usbcore to
-    some HCD that performs the I/O for the device driver.
-    </para>
-
-
-!Iinclude/linux/usb.h
-
-    </chapter>
-
-    <chapter id="usbcore"><title>USB Core APIs</title>
-
-    <para>There are two basic I/O models in the USB API.
-    The most elemental one is asynchronous:  drivers submit requests
-    in the form of an URB, and the URB's completion callback
-    handle the next step.
-    All USB transfer types support that model, although there
-    are special cases for control URBs (which always have setup
-    and status stages, but may not have a data stage) and
-    isochronous URBs (which allow large packets and include
-    per-packet fault reports).
-    Built on top of that is synchronous API support, where a
-    driver calls a routine that allocates one or more URBs,
-    submits them, and waits until they complete.
-    There are synchronous wrappers for single-buffer control
-    and bulk transfers (which are awkward to use in some
-    driver disconnect scenarios), and for scatterlist based
-    streaming i/o (bulk or interrupt).
-    </para>
-
-    <para>USB drivers need to provide buffers that can be
-    used for DMA, although they don't necessarily need to
-    provide the DMA mapping themselves.
-    There are APIs to use used when allocating DMA buffers,
-    which can prevent use of bounce buffers on some systems.
-    In some cases, drivers may be able to rely on 64bit DMA
-    to eliminate another kind of bounce buffer.
-    </para>
-
-!Edrivers/usb/core/urb.c
-!Edrivers/usb/core/message.c
-!Edrivers/usb/core/file.c
-!Edrivers/usb/core/driver.c
-!Edrivers/usb/core/usb.c
-!Edrivers/usb/core/hub.c
-    </chapter>
-
-    <chapter id="hcd"><title>Host Controller APIs</title>
-
-    <para>These APIs are only for use by host controller drivers,
-    most of which implement standard register interfaces such as
-    EHCI, OHCI, or UHCI.
-    UHCI was one of the first interfaces, designed by Intel and
-    also used by VIA; it doesn't do much in hardware.
-    OHCI was designed later, to have the hardware do more work
-    (bigger transfers, tracking protocol state, and so on).
-    EHCI was designed with USB 2.0; its design has features that
-    resemble OHCI (hardware does much more work) as well as
-    UHCI (some parts of ISO support, TD list processing).
-    </para>
-
-    <para>There are host controllers other than the "big three",
-    although most PCI based controllers (and a few non-PCI based
-    ones) use one of those interfaces.
-    Not all host controllers use DMA; some use PIO, and there
-    is also a simulator.
-    </para>
-
-    <para>The same basic APIs are available to drivers for all
-    those controllers.  
-    For historical reasons they are in two layers:
-    <structname>struct usb_bus</structname> is a rather thin
-    layer that became available in the 2.2 kernels, while
-    <structname>struct usb_hcd</structname> is a more featureful
-    layer (available in later 2.4 kernels and in 2.5) that
-    lets HCDs share common code, to shrink driver size
-    and significantly reduce hcd-specific behaviors.
-    </para>
-
-!Edrivers/usb/core/hcd.c
-!Edrivers/usb/core/hcd-pci.c
-!Idrivers/usb/core/buffer.c
-    </chapter>
-
-    <chapter id="usbfs">
-	<title>The USB Filesystem (usbfs)</title>
-
-	<para>This chapter presents the Linux <emphasis>usbfs</emphasis>.
-	You may prefer to avoid writing new kernel code for your
-	USB driver; that's the problem that usbfs set out to solve.
-	User mode device drivers are usually packaged as applications
-	or libraries, and may use usbfs through some programming library
-	that wraps it.  Such libraries include
-	<ulink url="http://libusb.sourceforge.net">libusb</ulink>
-	for C/C++, and
-	<ulink url="http://jUSB.sourceforge.net">jUSB</ulink> for Java.
-	</para>
-
-	<note><title>Unfinished</title>
-	    <para>This particular documentation is incomplete,
-	    especially with respect to the asynchronous mode.
-	    As of kernel 2.5.66 the code and this (new) documentation
-	    need to be cross-reviewed.
-	    </para>
-	    </note>
-
-	<para>Configure usbfs into Linux kernels by enabling the
-	<emphasis>USB filesystem</emphasis> option (CONFIG_USB_DEVICEFS),
-	and you get basic support for user mode USB device drivers.
-	Until relatively recently it was often (confusingly) called
-	<emphasis>usbdevfs</emphasis> although it wasn't solving what
-	<emphasis>devfs</emphasis> was.
-	Every USB device will appear in usbfs, regardless of whether or
-	not it has a kernel driver.
-	</para>
-
-	<sect1 id="usbfs-files">
-	    <title>What files are in "usbfs"?</title>
-
-	    <para>Conventionally mounted at
-	    <filename>/proc/bus/usb</filename>, usbfs 
-	    features include:
-	    <itemizedlist>
-		<listitem><para><filename>/proc/bus/usb/devices</filename>
-		    ... a text file
-		    showing each of the USB devices on known to the kernel,
-		    and their configuration descriptors.
-		    You can also poll() this to learn about new devices.
-		    </para></listitem>
-		<listitem><para><filename>/proc/bus/usb/BBB/DDD</filename>
-		    ... magic files
-		    exposing the each device's configuration descriptors, and
-		    supporting a series of ioctls for making device requests,
-		    including I/O to devices.  (Purely for access by programs.)
-		    </para></listitem>
-	    </itemizedlist>
-	    </para>
-
-	    <para> Each bus is given a number (BBB) based on when it was
-	    enumerated; within each bus, each device is given a similar
-	    number (DDD).
-	    Those BBB/DDD paths are not "stable" identifiers;
-	    expect them to change even if you always leave the devices
-	    plugged in to the same hub port.
-	    <emphasis>Don't even think of saving these in application
-	    configuration files.</emphasis>
-	    Stable identifiers are available, for user mode applications
-	    that want to use them.  HID and networking devices expose
-	    these stable IDs, so that for example you can be sure that
-	    you told the right UPS to power down its second server.
-	    "usbfs" doesn't (yet) expose those IDs.
-	    </para>
-
-	</sect1>
-
-	<sect1 id="usbfs-fstab">
-	    <title>Mounting and Access Control</title>
-
-	    <para>There are a number of mount options for usbfs, which will
-	    be of most interest to you if you need to override the default
-	    access control policy.
-	    That policy is that only root may read or write device files
-	    (<filename>/proc/bus/BBB/DDD</filename>) although anyone may read
-	    the <filename>devices</filename>
-	    or <filename>drivers</filename> files.
-	    I/O requests to the device also need the CAP_SYS_RAWIO capability,
-	    </para>
-
-	    <para>The significance of that is that by default, all user mode
-	    device drivers need super-user privileges.
-	    You can change modes or ownership in a driver setup
-	    when the device hotplugs, or maye just start the
-	    driver right then, as a privileged server (or some activity
-	    within one).
-	    That's the most secure approach for multi-user systems,
-	    but for single user systems ("trusted" by that user)
-	    it's more convenient just to grant everyone all access
-	    (using the <emphasis>devmode=0666</emphasis> option)
-	    so the driver can start whenever it's needed.
-	    </para>
-
-	    <para>The mount options for usbfs, usable in /etc/fstab or
-	    in command line invocations of <emphasis>mount</emphasis>, are:
-
-	    <variablelist>
-		<varlistentry>
-		    <term><emphasis>busgid</emphasis>=NNNNN</term>
-		    <listitem><para>Controls the GID used for the
-		    /proc/bus/usb/BBB
-		    directories.  (Default: 0)</para></listitem></varlistentry>
-		<varlistentry><term><emphasis>busmode</emphasis>=MMM</term>
-		    <listitem><para>Controls the file mode used for the
-		    /proc/bus/usb/BBB
-		    directories.  (Default: 0555)
-		    </para></listitem></varlistentry>
-		<varlistentry><term><emphasis>busuid</emphasis>=NNNNN</term>
-		    <listitem><para>Controls the UID used for the
-		    /proc/bus/usb/BBB
-		    directories.  (Default: 0)</para></listitem></varlistentry>
-
-		<varlistentry><term><emphasis>devgid</emphasis>=NNNNN</term>
-		    <listitem><para>Controls the GID used for the
-		    /proc/bus/usb/BBB/DDD
-		    files.  (Default: 0)</para></listitem></varlistentry>
-		<varlistentry><term><emphasis>devmode</emphasis>=MMM</term>
-		    <listitem><para>Controls the file mode used for the
-		    /proc/bus/usb/BBB/DDD
-		    files.  (Default: 0644)</para></listitem></varlistentry>
-		<varlistentry><term><emphasis>devuid</emphasis>=NNNNN</term>
-		    <listitem><para>Controls the UID used for the
-		    /proc/bus/usb/BBB/DDD
-		    files.  (Default: 0)</para></listitem></varlistentry>
-
-		<varlistentry><term><emphasis>listgid</emphasis>=NNNNN</term>
-		    <listitem><para>Controls the GID used for the
-		    /proc/bus/usb/devices and drivers files.
-		    (Default: 0)</para></listitem></varlistentry>
-		<varlistentry><term><emphasis>listmode</emphasis>=MMM</term>
-		    <listitem><para>Controls the file mode used for the
-		    /proc/bus/usb/devices and drivers files.
-		    (Default: 0444)</para></listitem></varlistentry>
-		<varlistentry><term><emphasis>listuid</emphasis>=NNNNN</term>
-		    <listitem><para>Controls the UID used for the
-		    /proc/bus/usb/devices and drivers files.
-		    (Default: 0)</para></listitem></varlistentry>
-	    </variablelist>
-
-	    </para>
-
-	    <para>Note that many Linux distributions hard-wire the mount options
-	    for usbfs in their init scripts, such as
-	    <filename>/etc/rc.d/rc.sysinit</filename>,
-	    rather than making it easy to set this per-system
-	    policy in <filename>/etc/fstab</filename>.
-	    </para>
-
-	</sect1>
-
-	<sect1 id="usbfs-devices">
-	    <title>/proc/bus/usb/devices</title>
-
-	    <para>This file is handy for status viewing tools in user
-	    mode, which can scan the text format and ignore most of it.
-	    More detailed device status (including class and vendor
-	    status) is available from device-specific files.
-	    For information about the current format of this file,
-	    see the
-	    <filename>Documentation/usb/proc_usb_info.txt</filename>
-	    file in your Linux kernel sources.
-	    </para>
-
-	    <para>This file, in combination with the poll() system call, can
-	    also be used to detect when devices are added or removed:
-<programlisting>int fd;
-struct pollfd pfd;
-
-fd = open("/proc/bus/usb/devices", O_RDONLY);
-pfd = { fd, POLLIN, 0 };
-for (;;) {
-	/* The first time through, this call will return immediately. */
-	poll(&amp;pfd, 1, -1);
-
-	/* To see what's changed, compare the file's previous and current
-	   contents or scan the filesystem.  (Scanning is more precise.) */
-}</programlisting>
-	    Note that this behavior is intended to be used for informational
-	    and debug purposes.  It would be more appropriate to use programs
-	    such as udev or HAL to initialize a device or start a user-mode
-	    helper program, for instance.
-	    </para>
-	</sect1>
-
-	<sect1 id="usbfs-bbbddd">
-	    <title>/proc/bus/usb/BBB/DDD</title>
-
-	    <para>Use these files in one of these basic ways:
-	    </para>
-
-	    <para><emphasis>They can be read,</emphasis>
-	    producing first the device descriptor
-	    (18 bytes) and then the descriptors for the current configuration.
-	    See the USB 2.0 spec for details about those binary data formats.
-	    You'll need to convert most multibyte values from little endian
-	    format to your native host byte order, although a few of the
-	    fields in the device descriptor (both of the BCD-encoded fields,
-	    and the vendor and product IDs) will be byteswapped for you.
-	    Note that configuration descriptors include descriptors for
-	    interfaces, altsettings, endpoints, and maybe additional
-	    class descriptors.
-	    </para>
-
-	    <para><emphasis>Perform USB operations</emphasis> using 
-	    <emphasis>ioctl()</emphasis> requests to make endpoint I/O
-	    requests (synchronously or asynchronously) or manage
-	    the device.
-	    These requests need the CAP_SYS_RAWIO capability,
-	    as well as filesystem access permissions.
-	    Only one ioctl request can be made on one of these
-	    device files at a time.
-	    This means that if you are synchronously reading an endpoint
-	    from one thread, you won't be able to write to a different
-	    endpoint from another thread until the read completes.
-	    This works for <emphasis>half duplex</emphasis> protocols,
-	    but otherwise you'd use asynchronous i/o requests. 
-	    </para>
-
-	    </sect1>
-
-
-	<sect1 id="usbfs-lifecycle">
-	    <title>Life Cycle of User Mode Drivers</title>
-
-	    <para>Such a driver first needs to find a device file
-	    for a device it knows how to handle.
-	    Maybe it was told about it because a
-	    <filename>/sbin/hotplug</filename> event handling agent
-	    chose that driver to handle the new device.
-	    Or maybe it's an application that scans all the
-	    /proc/bus/usb device files, and ignores most devices.
-	    In either case, it should <function>read()</function> all
-	    the descriptors from the device file,
-	    and check them against what it knows how to handle.
-	    It might just reject everything except a particular
-	    vendor and product ID, or need a more complex policy.
-	    </para>
-
-	    <para>Never assume there will only be one such device
-	    on the system at a time!
-	    If your code can't handle more than one device at
-	    a time, at least detect when there's more than one, and
-	    have your users choose which device to use.
-	    </para>
-
-	    <para>Once your user mode driver knows what device to use,
-	    it interacts with it in either of two styles.
-	    The simple style is to make only control requests; some
-	    devices don't need more complex interactions than those.
-	    (An example might be software using vendor-specific control
-	    requests for some initialization or configuration tasks,
-	    with a kernel driver for the rest.)
-	    </para>
-
-	    <para>More likely, you need a more complex style driver:
-	    one using non-control endpoints, reading or writing data
-	    and claiming exclusive use of an interface.
-	    <emphasis>Bulk</emphasis> transfers are easiest to use,
-	    but only their sibling <emphasis>interrupt</emphasis> transfers 
-	    work with low speed devices.
-	    Both interrupt and <emphasis>isochronous</emphasis> transfers
-	    offer service guarantees because their bandwidth is reserved.
-	    Such "periodic" transfers are awkward to use through usbfs,
-	    unless you're using the asynchronous calls.  However, interrupt
-	    transfers can also be used in a synchronous "one shot" style.
-	    </para>
-
-	    <para>Your user-mode driver should never need to worry
-	    about cleaning up request state when the device is
-	    disconnected, although it should close its open file
-	    descriptors as soon as it starts seeing the ENODEV
-	    errors.
-	    </para>
-
-	    </sect1>
-
-	<sect1 id="usbfs-ioctl"><title>The ioctl() Requests</title>
-
-	    <para>To use these ioctls, you need to include the following
-	    headers in your userspace program:
-<programlisting>#include &lt;linux/usb.h&gt;
-#include &lt;linux/usbdevice_fs.h&gt;
-#include &lt;asm/byteorder.h&gt;</programlisting>
-	    The standard USB device model requests, from "Chapter 9" of
-	    the USB 2.0 specification, are automatically included from
-	    the <filename>&lt;linux/usb/ch9.h&gt;</filename> header.
-	    </para>
-
-	    <para>Unless noted otherwise, the ioctl requests
-	    described here will
-	    update the modification time on the usbfs file to which
-	    they are applied (unless they fail).
-	    A return of zero indicates success; otherwise, a
-	    standard USB error code is returned.  (These are
-	    documented in
-	    <filename>Documentation/usb/error-codes.txt</filename>
-	    in your kernel sources.)
-	    </para>
-
-	    <para>Each of these files multiplexes access to several
-	    I/O streams, one per endpoint.
-	    Each device has one control endpoint (endpoint zero)
-	    which supports a limited RPC style RPC access.
-	    Devices are configured
-	    by hub_wq (in the kernel) setting a device-wide
-	    <emphasis>configuration</emphasis> that affects things
-	    like power consumption and basic functionality.
-	    The endpoints are part of USB <emphasis>interfaces</emphasis>,
-	    which may have <emphasis>altsettings</emphasis>
-	    affecting things like which endpoints are available.
-	    Many devices only have a single configuration and interface,
-	    so drivers for them will ignore configurations and altsettings.
-	    </para>
-
-
-	    <sect2 id="usbfs-mgmt">
-		<title>Management/Status Requests</title>
-
-		<para>A number of usbfs requests don't deal very directly
-		with device I/O.
-		They mostly relate to device management and status.
-		These are all synchronous requests.
-		</para>
-
-		<variablelist>
-
-		<varlistentry><term>USBDEVFS_CLAIMINTERFACE</term>
-		    <listitem><para>This is used to force usbfs to
-		    claim a specific interface,
-		    which has not previously been claimed by usbfs or any other
-		    kernel driver.
-		    The ioctl parameter is an integer holding the number of
-		    the interface (bInterfaceNumber from descriptor).
-		    </para><para>
-		    Note that if your driver doesn't claim an interface
-		    before trying to use one of its endpoints, and no
-		    other driver has bound to it, then the interface is
-		    automatically claimed by usbfs.
-		    </para><para>
-		    This claim will be released by a RELEASEINTERFACE ioctl,
-		    or by closing the file descriptor.
-		    File modification time is not updated by this request.
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_CONNECTINFO</term>
-		    <listitem><para>Says whether the device is lowspeed.
-		    The ioctl parameter points to a structure like this:
-<programlisting>struct usbdevfs_connectinfo {
-        unsigned int   devnum;
-        unsigned char  slow;
-}; </programlisting>
-		    File modification time is not updated by this request.
-		    </para><para>
-		    <emphasis>You can't tell whether a "not slow"
-		    device is connected at high speed (480 MBit/sec)
-		    or just full speed (12 MBit/sec).</emphasis>
-		    You should know the devnum value already,
-		    it's the DDD value of the device file name.
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_GETDRIVER</term>
-		    <listitem><para>Returns the name of the kernel driver
-		    bound to a given interface (a string).  Parameter
-		    is a pointer to this structure, which is modified:
-<programlisting>struct usbdevfs_getdriver {
-        unsigned int  interface;
-        char          driver[USBDEVFS_MAXDRIVERNAME + 1];
-};</programlisting>
-		    File modification time is not updated by this request.
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_IOCTL</term>
-		    <listitem><para>Passes a request from userspace through
-		    to a kernel driver that has an ioctl entry in the
-		    <emphasis>struct usb_driver</emphasis> it registered.
-<programlisting>struct usbdevfs_ioctl {
-        int     ifno;
-        int     ioctl_code;
-        void    *data;
-};
-
-/* user mode call looks like this.
- * 'request' becomes the driver->ioctl() 'code' parameter.
- * the size of 'param' is encoded in 'request', and that data
- * is copied to or from the driver->ioctl() 'buf' parameter.
- */
-static int
-usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
-{
-        struct usbdevfs_ioctl	wrapper;
-
-        wrapper.ifno = ifno;
-        wrapper.ioctl_code = request;
-        wrapper.data = param;
-
-        return ioctl (fd, USBDEVFS_IOCTL, &amp;wrapper);
-} </programlisting>
-		    File modification time is not updated by this request.
-		    </para><para>
-		    This request lets kernel drivers talk to user mode code
-		    through filesystem operations even when they don't create
-		    a character or block special device.
-		    It's also been used to do things like ask devices what
-		    device special file should be used.
-		    Two pre-defined ioctls are used
-		    to disconnect and reconnect kernel drivers, so
-		    that user mode code can completely manage binding
-		    and configuration of devices.
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_RELEASEINTERFACE</term>
-		    <listitem><para>This is used to release the claim usbfs
-		    made on interface, either implicitly or because of a
-		    USBDEVFS_CLAIMINTERFACE call, before the file
-		    descriptor is closed.
-		    The ioctl parameter is an integer holding the number of
-		    the interface (bInterfaceNumber from descriptor);
-		    File modification time is not updated by this request.
-		    </para><warning><para>
-		    <emphasis>No security check is made to ensure
-		    that the task which made the claim is the one
-		    which is releasing it.
-		    This means that user mode driver may interfere
-		    other ones.  </emphasis>
-		    </para></warning></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_RESETEP</term>
-		    <listitem><para>Resets the data toggle value for an endpoint
-		    (bulk or interrupt) to DATA0.
-		    The ioctl parameter is an integer endpoint number
-		    (1 to 15, as identified in the endpoint descriptor),
-		    with USB_DIR_IN added if the device's endpoint sends
-		    data to the host.
-		    </para><warning><para>
-		    <emphasis>Avoid using this request.
-		    It should probably be removed.</emphasis>
-		    Using it typically means the device and driver will lose
-		    toggle synchronization.  If you really lost synchronization,
-		    you likely need to completely handshake with the device,
-		    using a request like CLEAR_HALT
-		    or SET_INTERFACE.
-		    </para></warning></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_DROP_PRIVILEGES</term>
-		    <listitem><para>This is used to relinquish the ability
-		    to do certain operations which are considered to be
-		    privileged on a usbfs file descriptor.
-		    This includes claiming arbitrary interfaces, resetting
-		    a device on which there are currently claimed interfaces
-		    from other users, and issuing USBDEVFS_IOCTL calls.
-		    The ioctl parameter is a 32 bit mask of interfaces
-		    the user is allowed to claim on this file descriptor.
-		    You may issue this ioctl more than one time to narrow
-		    said mask.
-		    </para></listitem></varlistentry>
-		</variablelist>
-
-		</sect2>
-
-	    <sect2 id="usbfs-sync">
-		<title>Synchronous I/O Support</title>
-
-		<para>Synchronous requests involve the kernel blocking
-		until the user mode request completes, either by
-		finishing successfully or by reporting an error.
-		In most cases this is the simplest way to use usbfs,
-		although as noted above it does prevent performing I/O
-		to more than one endpoint at a time.
-		</para>
-
-		<variablelist>
-
-		<varlistentry><term>USBDEVFS_BULK</term>
-		    <listitem><para>Issues a bulk read or write request to the
-		    device.
-		    The ioctl parameter is a pointer to this structure:
-<programlisting>struct usbdevfs_bulktransfer {
-        unsigned int  ep;
-        unsigned int  len;
-        unsigned int  timeout; /* in milliseconds */
-        void          *data;
-};</programlisting>
-		    </para><para>The "ep" value identifies a
-		    bulk endpoint number (1 to 15, as identified in an endpoint
-		    descriptor),
-		    masked with USB_DIR_IN when referring to an endpoint which
-		    sends data to the host from the device.
-		    The length of the data buffer is identified by "len";
-		    Recent kernels support requests up to about 128KBytes.
-		    <emphasis>FIXME say how read length is returned,
-		    and how short reads are handled.</emphasis>.
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_CLEAR_HALT</term>
-		    <listitem><para>Clears endpoint halt (stall) and
-		    resets the endpoint toggle.  This is only
-		    meaningful for bulk or interrupt endpoints.
-		    The ioctl parameter is an integer endpoint number
-		    (1 to 15, as identified in an endpoint descriptor),
-		    masked with USB_DIR_IN when referring to an endpoint which
-		    sends data to the host from the device.
-		    </para><para>
-		    Use this on bulk or interrupt endpoints which have
-		    stalled, returning <emphasis>-EPIPE</emphasis> status
-		    to a data transfer request.
-		    Do not issue the control request directly, since
-		    that could invalidate the host's record of the
-		    data toggle.
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_CONTROL</term>
-		    <listitem><para>Issues a control request to the device.
-		    The ioctl parameter points to a structure like this:
-<programlisting>struct usbdevfs_ctrltransfer {
-        __u8   bRequestType;
-        __u8   bRequest;
-        __u16  wValue;
-        __u16  wIndex;
-        __u16  wLength;
-        __u32  timeout;  /* in milliseconds */
-        void   *data;
-};</programlisting>
-		    </para><para>
-		    The first eight bytes of this structure are the contents
-		    of the SETUP packet to be sent to the device; see the
-		    USB 2.0 specification for details.
-		    The bRequestType value is composed by combining a
-		    USB_TYPE_* value, a USB_DIR_* value, and a
-		    USB_RECIP_* value (from
-		    <emphasis>&lt;linux/usb.h&gt;</emphasis>).
-		    If wLength is nonzero, it describes the length of the data
-		    buffer, which is either written to the device
-		    (USB_DIR_OUT) or read from the device (USB_DIR_IN).
-		    </para><para>
-		    At this writing, you can't transfer more than 4 KBytes
-		    of data to or from a device; usbfs has a limit, and
-		    some host controller drivers have a limit.
-		    (That's not usually a problem.)
-		    <emphasis>Also</emphasis> there's no way to say it's
-		    not OK to get a short read back from the device.
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_RESET</term>
-		    <listitem><para>Does a USB level device reset.
-		    The ioctl parameter is ignored.
-		    After the reset, this rebinds all device interfaces.
-		    File modification time is not updated by this request.
-		    </para><warning><para>
-		    <emphasis>Avoid using this call</emphasis>
-		    until some usbcore bugs get fixed,
-		    since it does not fully synchronize device, interface,
-		    and driver (not just usbfs) state.
-		    </para></warning></listitem></varlistentry>
-	    
-		<varlistentry><term>USBDEVFS_SETINTERFACE</term>
-		    <listitem><para>Sets the alternate setting for an
-		    interface.  The ioctl parameter is a pointer to a
-		    structure like this:
-<programlisting>struct usbdevfs_setinterface {
-        unsigned int  interface;
-        unsigned int  altsetting;
-}; </programlisting>
-		    File modification time is not updated by this request.
-		    </para><para>
-		    Those struct members are from some interface descriptor
-		    applying to the current configuration.
-		    The interface number is the bInterfaceNumber value, and
-		    the altsetting number is the bAlternateSetting value.
-		    (This resets each endpoint in the interface.)
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_SETCONFIGURATION</term>
-		    <listitem><para>Issues the
-		    <function>usb_set_configuration</function> call
-		    for the device.
-		    The parameter is an integer holding the number of
-		    a configuration (bConfigurationValue from descriptor).
-		    File modification time is not updated by this request.
-		    </para><warning><para>
-		    <emphasis>Avoid using this call</emphasis>
-		    until some usbcore bugs get fixed,
-		    since it does not fully synchronize device, interface,
-		    and driver (not just usbfs) state.
-		    </para></warning></listitem></varlistentry>
-
-		</variablelist>
-	    </sect2>
-
-	    <sect2 id="usbfs-async">
-		<title>Asynchronous I/O Support</title>
-
-		<para>As mentioned above, there are situations where it may be
-		important to initiate concurrent operations from user mode code.
-		This is particularly important for periodic transfers
-		(interrupt and isochronous), but it can be used for other
-		kinds of USB requests too.
-		In such cases, the asynchronous requests described here
-		are essential.  Rather than submitting one request and having
-		the kernel block until it completes, the blocking is separate.
-		</para>
-
-		<para>These requests are packaged into a structure that
-		resembles the URB used by kernel device drivers.
-		(No POSIX Async I/O support here, sorry.)
-		It identifies the endpoint type (USBDEVFS_URB_TYPE_*),
-		endpoint (number, masked with USB_DIR_IN as appropriate),
-		buffer and length, and a user "context" value serving to
-		uniquely identify each request.
-		(It's usually a pointer to per-request data.)
-		Flags can modify requests (not as many as supported for
-		kernel drivers).
-		</para>
-
-		<para>Each request can specify a realtime signal number
-		(between SIGRTMIN and SIGRTMAX, inclusive) to request a
-		signal be sent when the request completes.
-		</para>
-
-		<para>When usbfs returns these urbs, the status value
-		is updated, and the buffer may have been modified.
-		Except for isochronous transfers, the actual_length is
-		updated to say how many bytes were transferred; if the
-		USBDEVFS_URB_DISABLE_SPD flag is set
-		("short packets are not OK"), if fewer bytes were read
-		than were requested then you get an error report.
-		</para>
-
-<programlisting>struct usbdevfs_iso_packet_desc {
-        unsigned int                     length;
-        unsigned int                     actual_length;
-        unsigned int                     status;
-};
-
-struct usbdevfs_urb {
-        unsigned char                    type;
-        unsigned char                    endpoint;
-        int                              status;
-        unsigned int                     flags;
-        void                             *buffer;
-        int                              buffer_length;
-        int                              actual_length;
-        int                              start_frame;
-        int                              number_of_packets;
-        int                              error_count;
-        unsigned int                     signr;
-        void                             *usercontext;
-        struct usbdevfs_iso_packet_desc  iso_frame_desc[];
-};</programlisting>
-
-		<para> For these asynchronous requests, the file modification
-		time reflects when the request was initiated.
-		This contrasts with their use with the synchronous requests,
-		where it reflects when requests complete.
-		</para>
-
-		<variablelist>
-
-		<varlistentry><term>USBDEVFS_DISCARDURB</term>
-		    <listitem><para>
-		    <emphasis>TBS</emphasis>
-		    File modification time is not updated by this request.
-		    </para><para>
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_DISCSIGNAL</term>
-		    <listitem><para>
-		    <emphasis>TBS</emphasis>
-		    File modification time is not updated by this request.
-		    </para><para>
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_REAPURB</term>
-		    <listitem><para>
-		    <emphasis>TBS</emphasis>
-		    File modification time is not updated by this request.
-		    </para><para>
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_REAPURBNDELAY</term>
-		    <listitem><para>
-		    <emphasis>TBS</emphasis>
-		    File modification time is not updated by this request.
-		    </para><para>
-		    </para></listitem></varlistentry>
-
-		<varlistentry><term>USBDEVFS_SUBMITURB</term>
-		    <listitem><para>
-		    <emphasis>TBS</emphasis>
-		    </para><para>
-		    </para></listitem></varlistentry>
-
-		</variablelist>
-	    </sect2>
-
-	</sect1>
-
-    </chapter>
-
-</book>
-<!-- vim:syntax=sgml:sw=4
--->
diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl
deleted file mode 100644
index a27ab9f5..0000000
--- a/Documentation/DocBook/writing-an-alsa-driver.tmpl
+++ /dev/null
@@ -1,6206 +0,0 @@
-<?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" []>
-
-<!-- ****************************************************** -->
-<!-- Header  -->
-<!-- ****************************************************** -->
-<book id="Writing-an-ALSA-Driver">
-  <bookinfo>
-    <title>Writing an ALSA Driver</title>
-    <author>
-      <firstname>Takashi</firstname>
-      <surname>Iwai</surname>
-      <affiliation>
-        <address>
-          <email>tiwai@suse.de</email>
-        </address>
-      </affiliation>
-     </author>
-
-     <date>Oct 15, 2007</date>
-     <edition>0.3.7</edition>
-
-    <abstract>
-      <para>
-        This document describes how to write an ALSA (Advanced Linux
-        Sound Architecture) driver.
-      </para>
-    </abstract>
-
-    <legalnotice>
-    <para>
-    Copyright (c) 2002-2005  Takashi Iwai <email>tiwai@suse.de</email>
-    </para>
-
-    <para>
-    This document is free; 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 document is distributed in the hope that it will be useful,
-    but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the
-    implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A
-    PARTICULAR PURPOSE</emphasis>. 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>
-    </legalnotice>
-
-  </bookinfo>
-
-<!-- ****************************************************** -->
-<!-- Preface  -->
-<!-- ****************************************************** -->
-  <preface id="preface">
-    <title>Preface</title>
-    <para>
-      This document describes how to write an
-      <ulink url="http://www.alsa-project.org/"><citetitle>
-      ALSA (Advanced Linux Sound Architecture)</citetitle></ulink>
-      driver. The document focuses mainly on PCI soundcards.
-      In the case of other device types, the API might
-      be different, too. However, at least the ALSA kernel API is
-      consistent, and therefore it would be still a bit help for
-      writing them.
-    </para>
-
-    <para>
-    This document targets people who already have enough
-    C language skills and have basic linux kernel programming
-    knowledge.  This document doesn't explain the general
-    topic of linux kernel coding and doesn't cover low-level
-    driver implementation details. It only describes
-    the standard way to write a PCI sound driver on ALSA.
-    </para>
-
-    <para>
-      If you are already familiar with the older ALSA ver.0.5.x API, you
-    can check the drivers such as <filename>sound/pci/es1938.c</filename> or
-    <filename>sound/pci/maestro3.c</filename> which have also almost the same
-    code-base in the ALSA 0.5.x tree, so you can compare the differences.
-    </para>
-
-    <para>
-      This document is still a draft version. Any feedback and
-    corrections, please!!
-    </para>
-  </preface>
-
-
-<!-- ****************************************************** -->
-<!-- File Tree Structure  -->
-<!-- ****************************************************** -->
-  <chapter id="file-tree">
-    <title>File Tree Structure</title>
-
-    <section id="file-tree-general">
-      <title>General</title>
-      <para>
-        The ALSA drivers are provided in two ways.
-      </para>
-
-      <para>
-        One is the trees provided as a tarball or via cvs from the
-      ALSA's ftp site, and another is the 2.6 (or later) Linux kernel
-      tree. To synchronize both, the ALSA driver tree is split into
-      two different trees: alsa-kernel and alsa-driver. The former
-      contains purely the source code for the Linux 2.6 (or later)
-      tree. This tree is designed only for compilation on 2.6 or
-      later environment. The latter, alsa-driver, contains many subtle
-      files for compiling ALSA drivers outside of the Linux kernel tree,
-      wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API,
-      and additional drivers which are still in development or in
-      tests.  The drivers in alsa-driver tree will be moved to
-      alsa-kernel (and eventually to the 2.6 kernel tree) when they are
-      finished and confirmed to work fine.
-      </para>
-
-      <para>
-        The file tree structure of ALSA driver is depicted below. Both
-        alsa-kernel and alsa-driver have almost the same file
-        structure, except for <quote>core</quote> directory. It's
-        named as <quote>acore</quote> in alsa-driver tree. 
-
-        <example>
-          <title>ALSA File Tree Structure</title>
-          <literallayout>
-        sound
-                /core
-                        /oss
-                        /seq
-                                /oss
-                                /instr
-                /ioctl32
-                /include
-                /drivers
-                        /mpu401
-                        /opl3
-                /i2c
-                        /l3
-                /synth
-                        /emux
-                /pci
-                        /(cards)
-                /isa
-                        /(cards)
-                /arm
-                /ppc
-                /sparc
-                /usb
-                /pcmcia /(cards)
-                /oss
-          </literallayout>
-        </example>
-      </para>
-    </section>
-
-    <section id="file-tree-core-directory">
-      <title>core directory</title>
-      <para>
-        This directory contains the middle layer which is the heart
-      of ALSA drivers. In this directory, the native ALSA modules are
-      stored. The sub-directories contain different modules and are
-      dependent upon the kernel config. 
-      </para>
-
-      <section id="file-tree-core-directory-oss">
-        <title>core/oss</title>
-
-        <para>
-          The codes for PCM and mixer OSS emulation modules are stored
-        in this directory. The rawmidi OSS emulation is included in
-        the ALSA rawmidi code since it's quite small. The sequencer
-        code is stored in <filename>core/seq/oss</filename> directory (see
-        <link linkend="file-tree-core-directory-seq-oss"><citetitle>
-        below</citetitle></link>).
-        </para>
-      </section>
-
-      <section id="file-tree-core-directory-ioctl32">
-        <title>core/ioctl32</title>
-
-        <para>
-          This directory contains the 32bit-ioctl wrappers for 64bit
-        architectures such like x86-64, ppc64 and sparc64. For 32bit
-        and alpha architectures, these are not compiled. 
-        </para>
-      </section>
-
-      <section id="file-tree-core-directory-seq">
-        <title>core/seq</title>
-        <para>
-          This directory and its sub-directories are for the ALSA
-        sequencer. This directory contains the sequencer core and
-        primary sequencer modules such like snd-seq-midi,
-        snd-seq-virmidi, etc. They are compiled only when
-        <constant>CONFIG_SND_SEQUENCER</constant> is set in the kernel
-        config. 
-        </para>
-      </section>
-
-      <section id="file-tree-core-directory-seq-oss">
-        <title>core/seq/oss</title>
-        <para>
-          This contains the OSS sequencer emulation codes.
-        </para>
-      </section>
-
-      <section id="file-tree-core-directory-deq-instr">
-        <title>core/seq/instr</title>
-        <para>
-          This directory contains the modules for the sequencer
-        instrument layer. 
-        </para>
-      </section>
-    </section>
-
-    <section id="file-tree-include-directory">
-      <title>include directory</title>
-      <para>
-        This is the place for the public header files of ALSA drivers,
-      which are to be exported to user-space, or included by
-      several files at different directories. Basically, the private
-      header files should not be placed in this directory, but you may
-      still find files there, due to historical reasons :) 
-      </para>
-    </section>
-
-    <section id="file-tree-drivers-directory">
-      <title>drivers directory</title>
-      <para>
-        This directory contains code shared among different drivers
-      on different architectures.  They are hence supposed not to be
-      architecture-specific.
-      For example, the dummy pcm driver and the serial MIDI
-      driver are found in this directory. In the sub-directories,
-      there is code for components which are independent from
-      bus and cpu architectures. 
-      </para>
-
-      <section id="file-tree-drivers-directory-mpu401">
-        <title>drivers/mpu401</title>
-        <para>
-          The MPU401 and MPU401-UART modules are stored here.
-        </para>
-      </section>
-
-      <section id="file-tree-drivers-directory-opl3">
-        <title>drivers/opl3 and opl4</title>
-        <para>
-          The OPL3 and OPL4 FM-synth stuff is found here.
-        </para>
-      </section>
-    </section>
-
-    <section id="file-tree-i2c-directory">
-      <title>i2c directory</title>
-      <para>
-        This contains the ALSA i2c components.
-      </para>
-
-      <para>
-        Although there is a standard i2c layer on Linux, ALSA has its
-      own i2c code for some cards, because the soundcard needs only a
-      simple operation and the standard i2c API is too complicated for
-      such a purpose. 
-      </para>
-
-      <section id="file-tree-i2c-directory-l3">
-        <title>i2c/l3</title>
-        <para>
-          This is a sub-directory for ARM L3 i2c.
-        </para>
-      </section>
-    </section>
-
-    <section id="file-tree-synth-directory">
-        <title>synth directory</title>
-        <para>
-          This contains the synth middle-level modules.
-        </para>
-
-        <para>
-          So far, there is only Emu8000/Emu10k1 synth driver under
-        the <filename>synth/emux</filename> sub-directory. 
-        </para>
-    </section>
-
-    <section id="file-tree-pci-directory">
-      <title>pci directory</title>
-      <para>
-        This directory and its sub-directories hold the top-level card modules
-      for PCI soundcards and the code specific to the PCI BUS.
-      </para>
-
-      <para>
-        The drivers compiled from a single file are stored directly
-      in the pci directory, while the drivers with several source files are
-      stored on their own sub-directory (e.g. emu10k1, ice1712). 
-      </para>
-    </section>
-
-    <section id="file-tree-isa-directory">
-      <title>isa directory</title>
-      <para>
-        This directory and its sub-directories hold the top-level card modules
-      for ISA soundcards. 
-      </para>
-    </section>
-
-    <section id="file-tree-arm-ppc-sparc-directories">
-      <title>arm, ppc, and sparc directories</title>
-      <para>
-        They are used for top-level card modules which are
-      specific to one of these architectures. 
-      </para>
-    </section>
-
-    <section id="file-tree-usb-directory">
-      <title>usb directory</title>
-      <para>
-        This directory contains the USB-audio driver. In the latest version, the
-      USB MIDI driver is integrated in the usb-audio driver. 
-      </para>
-    </section>
-
-    <section id="file-tree-pcmcia-directory">
-      <title>pcmcia directory</title>
-      <para>
-        The PCMCIA, especially PCCard drivers will go here. CardBus
-      drivers will be in the pci directory, because their API is identical
-      to that of standard PCI cards. 
-      </para>
-    </section>
-
-    <section id="file-tree-oss-directory">
-      <title>oss directory</title>
-      <para>
-        The OSS/Lite source files are stored here in Linux 2.6 (or
-      later) tree. In the ALSA driver tarball, this directory is empty,
-      of course :) 
-      </para>
-    </section>
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Basic Flow for PCI Drivers  -->
-<!-- ****************************************************** -->
-  <chapter id="basic-flow">
-    <title>Basic Flow for PCI Drivers</title>
-
-    <section id="basic-flow-outline">
-      <title>Outline</title>
-      <para>
-        The minimum flow for PCI soundcards is as follows:
-
-        <itemizedlist>
-          <listitem><para>define the PCI ID table (see the section
-          <link linkend="pci-resource-entries"><citetitle>PCI Entries
-          </citetitle></link>).</para></listitem> 
-          <listitem><para>create <function>probe()</function> callback.</para></listitem>
-          <listitem><para>create <function>remove()</function> callback.</para></listitem>
-          <listitem><para>create a <structname>pci_driver</structname> structure
-	  containing the three pointers above.</para></listitem>
-          <listitem><para>create an <function>init()</function> function just calling
-	  the <function>pci_register_driver()</function> to register the pci_driver table
-	  defined above.</para></listitem>
-          <listitem><para>create an <function>exit()</function> function to call
-	  the <function>pci_unregister_driver()</function> function.</para></listitem>
-        </itemizedlist>
-      </para>
-    </section>
-
-    <section id="basic-flow-example">
-      <title>Full Code Example</title>
-      <para>
-        The code example is shown below. Some parts are kept
-      unimplemented at this moment but will be filled in the
-      next sections. The numbers in the comment lines of the
-      <function>snd_mychip_probe()</function> function
-      refer to details explained in the following section. 
-
-        <example>
-          <title>Basic Flow for PCI Drivers - Example</title>
-          <programlisting>
-<![CDATA[
-  #include <linux/init.h>
-  #include <linux/pci.h>
-  #include <linux/slab.h>
-  #include <sound/core.h>
-  #include <sound/initval.h>
-
-  /* module parameters (see "Module Parameters") */
-  /* SNDRV_CARDS: maximum number of cards supported by this module */
-  static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
-  static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
-  static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
-
-  /* definition of the chip-specific record */
-  struct mychip {
-          struct snd_card *card;
-          /* the rest of the implementation will be in section
-           * "PCI Resource Management"
-           */
-  };
-
-  /* chip-specific destructor
-   * (see "PCI Resource Management")
-   */
-  static int snd_mychip_free(struct mychip *chip)
-  {
-          .... /* will be implemented later... */
-  }
-
-  /* component-destructor
-   * (see "Management of Cards and Components")
-   */
-  static int snd_mychip_dev_free(struct snd_device *device)
-  {
-          return snd_mychip_free(device->device_data);
-  }
-
-  /* chip-specific constructor
-   * (see "Management of Cards and Components")
-   */
-  static int snd_mychip_create(struct snd_card *card,
-                               struct pci_dev *pci,
-                               struct mychip **rchip)
-  {
-          struct mychip *chip;
-          int err;
-          static struct snd_device_ops ops = {
-                 .dev_free = snd_mychip_dev_free,
-          };
-
-          *rchip = NULL;
-
-          /* check PCI availability here
-           * (see "PCI Resource Management")
-           */
-          ....
-
-          /* allocate a chip-specific data with zero filled */
-          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
-          if (chip == NULL)
-                  return -ENOMEM;
-
-          chip->card = card;
-
-          /* rest of initialization here; will be implemented
-           * later, see "PCI Resource Management"
-           */
-          ....
-
-          err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
-          if (err < 0) {
-                  snd_mychip_free(chip);
-                  return err;
-          }
-
-          *rchip = chip;
-          return 0;
-  }
-
-  /* constructor -- see "Constructor" sub-section */
-  static int snd_mychip_probe(struct pci_dev *pci,
-                              const struct pci_device_id *pci_id)
-  {
-          static int dev;
-          struct snd_card *card;
-          struct mychip *chip;
-          int err;
-
-          /* (1) */
-          if (dev >= SNDRV_CARDS)
-                  return -ENODEV;
-          if (!enable[dev]) {
-                  dev++;
-                  return -ENOENT;
-          }
-
-          /* (2) */
-          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
-                             0, &card);
-          if (err < 0)
-                  return err;
-
-          /* (3) */
-          err = snd_mychip_create(card, pci, &chip);
-          if (err < 0) {
-                  snd_card_free(card);
-                  return err;
-          }
-
-          /* (4) */
-          strcpy(card->driver, "My Chip");
-          strcpy(card->shortname, "My Own Chip 123");
-          sprintf(card->longname, "%s at 0x%lx irq %i",
-                  card->shortname, chip->ioport, chip->irq);
-
-          /* (5) */
-          .... /* implemented later */
-
-          /* (6) */
-          err = snd_card_register(card);
-          if (err < 0) {
-                  snd_card_free(card);
-                  return err;
-          }
-
-          /* (7) */
-          pci_set_drvdata(pci, card);
-          dev++;
-          return 0;
-  }
-
-  /* destructor -- see the "Destructor" sub-section */
-  static void snd_mychip_remove(struct pci_dev *pci)
-  {
-          snd_card_free(pci_get_drvdata(pci));
-          pci_set_drvdata(pci, NULL);
-  }
-]]>
-          </programlisting>
-        </example>
-      </para>
-    </section>
-
-    <section id="basic-flow-constructor">
-      <title>Constructor</title>
-      <para>
-        The real constructor of PCI drivers is the <function>probe</function> callback.
-      The <function>probe</function> callback and other component-constructors which are called
-      from the <function>probe</function> callback cannot be used with
-      the <parameter>__init</parameter> prefix
-      because any PCI device could be a hotplug device. 
-      </para>
-
-      <para>
-        In the <function>probe</function> callback, the following scheme is often used.
-      </para>
-
-      <section id="basic-flow-constructor-device-index">
-        <title>1) Check and increment the device index.</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int dev;
-  ....
-  if (dev >= SNDRV_CARDS)
-          return -ENODEV;
-  if (!enable[dev]) {
-          dev++;
-          return -ENOENT;
-  }
-]]>
-            </programlisting>
-          </informalexample>
-
-        where enable[dev] is the module option.
-        </para>
-
-        <para>
-          Each time the <function>probe</function> callback is called, check the
-        availability of the device. If not available, simply increment
-        the device index and returns. dev will be incremented also
-        later (<link
-        linkend="basic-flow-constructor-set-pci"><citetitle>step
-        7</citetitle></link>). 
-        </para>
-      </section>
-
-      <section id="basic-flow-constructor-create-card">
-        <title>2) Create a card instance</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  struct snd_card *card;
-  int err;
-  ....
-  err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
-                     0, &card);
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-          The details will be explained in the section
-          <link linkend="card-management-card-instance"><citetitle>
-          Management of Cards and Components</citetitle></link>.
-        </para>
-      </section>
-
-      <section id="basic-flow-constructor-create-main">
-        <title>3) Create a main component</title>
-        <para>
-          In this part, the PCI resources are allocated.
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  struct mychip *chip;
-  ....
-  err = snd_mychip_create(card, pci, &chip);
-  if (err < 0) {
-          snd_card_free(card);
-          return err;
-  }
-]]>
-            </programlisting>
-          </informalexample>
-
-          The details will be explained in the section <link
-        linkend="pci-resource"><citetitle>PCI Resource
-        Management</citetitle></link>.
-        </para>
-      </section>
-
-      <section id="basic-flow-constructor-main-component">
-        <title>4) Set the driver ID and name strings.</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  strcpy(card->driver, "My Chip");
-  strcpy(card->shortname, "My Own Chip 123");
-  sprintf(card->longname, "%s at 0x%lx irq %i",
-          card->shortname, chip->ioport, chip->irq);
-]]>
-            </programlisting>
-          </informalexample>
-
-          The driver field holds the minimal ID string of the
-        chip. This is used by alsa-lib's configurator, so keep it
-        simple but unique. 
-          Even the same driver can have different driver IDs to
-        distinguish the functionality of each chip type. 
-        </para>
-
-        <para>
-          The shortname field is a string shown as more verbose
-        name. The longname field contains the information
-        shown in <filename>/proc/asound/cards</filename>. 
-        </para>
-      </section>
-
-      <section id="basic-flow-constructor-create-other">
-        <title>5) Create other components, such as mixer, MIDI, etc.</title>
-        <para>
-          Here you define the basic components such as
-          <link linkend="pcm-interface"><citetitle>PCM</citetitle></link>,
-          mixer (e.g. <link linkend="api-ac97"><citetitle>AC97</citetitle></link>),
-          MIDI (e.g. <link linkend="midi-interface"><citetitle>MPU-401</citetitle></link>),
-          and other interfaces.
-          Also, if you want a <link linkend="proc-interface"><citetitle>proc
-        file</citetitle></link>, define it here, too.
-        </para>
-      </section>
-
-      <section id="basic-flow-constructor-register-card">
-        <title>6) Register the card instance.</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  err = snd_card_register(card);
-  if (err < 0) {
-          snd_card_free(card);
-          return err;
-  }
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-          Will be explained in the section <link
-        linkend="card-management-registration"><citetitle>Management
-        of Cards and Components</citetitle></link>, too. 
-        </para>
-      </section>
-
-      <section id="basic-flow-constructor-set-pci">
-        <title>7) Set the PCI driver data and return zero.</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-        pci_set_drvdata(pci, card);
-        dev++;
-        return 0;
-]]>
-            </programlisting>
-          </informalexample>
-
-          In the above, the card record is stored. This pointer is
-        used in the remove callback and power-management
-        callbacks, too. 
-        </para>
-      </section>
-    </section>
-
-    <section id="basic-flow-destructor">
-      <title>Destructor</title>
-      <para>
-        The destructor, remove callback, simply releases the card
-      instance. Then the ALSA middle layer will release all the
-      attached components automatically. 
-      </para>
-
-      <para>
-        It would be typically like the following:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static void snd_mychip_remove(struct pci_dev *pci)
-  {
-          snd_card_free(pci_get_drvdata(pci));
-          pci_set_drvdata(pci, NULL);
-  }
-]]>
-          </programlisting>
-        </informalexample>
-
-        The above code assumes that the card pointer is set to the PCI
-	driver data.
-      </para>
-    </section>
-
-    <section id="basic-flow-header-files">
-      <title>Header Files</title>
-      <para>
-        For the above example, at least the following include files
-      are necessary. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  #include <linux/init.h>
-  #include <linux/pci.h>
-  #include <linux/slab.h>
-  #include <sound/core.h>
-  #include <sound/initval.h>
-]]>
-          </programlisting>
-        </informalexample>
-
-	where the last one is necessary only when module options are
-      defined in the source file.  If the code is split into several
-      files, the files without module options don't need them.
-      </para>
-
-      <para>
-        In addition to these headers, you'll need
-      <filename>&lt;linux/interrupt.h&gt;</filename> for interrupt
-      handling, and <filename>&lt;asm/io.h&gt;</filename> for I/O
-      access. If you use the <function>mdelay()</function> or
-      <function>udelay()</function> functions, you'll need to include
-      <filename>&lt;linux/delay.h&gt;</filename> too. 
-      </para>
-
-      <para>
-      The ALSA interfaces like the PCM and control APIs are defined in other
-      <filename>&lt;sound/xxx.h&gt;</filename> header files.
-      They have to be included after
-      <filename>&lt;sound/core.h&gt;</filename>.
-      </para>
-
-    </section>
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Management of Cards and Components  -->
-<!-- ****************************************************** -->
-  <chapter id="card-management">
-    <title>Management of Cards and Components</title>
-
-    <section id="card-management-card-instance">
-      <title>Card Instance</title>
-      <para>
-      For each soundcard, a <quote>card</quote> record must be allocated.
-      </para>
-
-      <para>
-      A card record is the headquarters of the soundcard.  It manages
-      the whole list of devices (components) on the soundcard, such as
-      PCM, mixers, MIDI, synthesizer, and so on.  Also, the card
-      record holds the ID and the name strings of the card, manages
-      the root of proc files, and controls the power-management states
-      and hotplug disconnections.  The component list on the card
-      record is used to manage the correct release of resources at
-      destruction. 
-      </para>
-
-      <para>
-        As mentioned above, to create a card instance, call
-      <function>snd_card_new()</function>.
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_card *card;
-  int err;
-  err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The function takes six arguments: the parent device pointer,
-        the card-index number, the id string, the module pointer (usually
-        <constant>THIS_MODULE</constant>),
-        the size of extra-data space, and the pointer to return the
-        card instance.  The extra_size argument is used to
-        allocate card-&gt;private_data for the
-        chip-specific data.  Note that these data
-        are allocated by <function>snd_card_new()</function>.
-      </para>
-
-      <para>
-	The first argument, the pointer of struct
-	<structname>device</structname>, specifies the parent device.
-	For PCI devices, typically &amp;pci-&gt; is passed there.
-      </para>
-    </section>
-
-    <section id="card-management-component">
-      <title>Components</title>
-      <para>
-        After the card is created, you can attach the components
-      (devices) to the card instance. In an ALSA driver, a component is
-      represented as a struct <structname>snd_device</structname> object.
-      A component can be a PCM instance, a control interface, a raw
-      MIDI interface, etc.  Each such instance has one component
-      entry.
-      </para>
-
-      <para>
-        A component can be created via
-        <function>snd_device_new()</function> function. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        This takes the card pointer, the device-level
-      (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the
-      callback pointers (<parameter>&amp;ops</parameter>). The
-      device-level defines the type of components and the order of
-      registration and de-registration.  For most components, the
-      device-level is already defined.  For a user-defined component,
-      you can use <constant>SNDRV_DEV_LOWLEVEL</constant>.
-      </para>
-
-      <para>
-      This function itself doesn't allocate the data space. The data
-      must be allocated manually beforehand, and its pointer is passed
-      as the argument. This pointer (<parameter>chip</parameter> in the
-      above example) is used as the identifier for the instance.
-      </para>
-
-      <para>
-        Each pre-defined ALSA component such as ac97 and pcm calls
-      <function>snd_device_new()</function> inside its
-      constructor. The destructor for each component is defined in the
-      callback pointers.  Hence, you don't need to take care of
-      calling a destructor for such a component.
-      </para>
-
-      <para>
-        If you wish to create your own component, you need to
-      set the destructor function to the dev_free callback in
-      the <parameter>ops</parameter>, so that it can be released
-      automatically via <function>snd_card_free()</function>.
-      The next example will show an implementation of chip-specific
-      data.
-      </para>
-    </section>
-
-    <section id="card-management-chip-specific">
-      <title>Chip-Specific Data</title>
-      <para>
-      Chip-specific information, e.g. the I/O port address, its
-      resource pointer, or the irq number, is stored in the
-      chip-specific record.
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct mychip {
-          ....
-  };
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        In general, there are two ways of allocating the chip record.
-      </para>
-
-      <section id="card-management-chip-specific-snd-card-new">
-        <title>1. Allocating via <function>snd_card_new()</function>.</title>
-        <para>
-          As mentioned above, you can pass the extra-data-length
-	  to the 5th argument of <function>snd_card_new()</function>, i.e.
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
-                     sizeof(struct mychip), &card);
-]]>
-            </programlisting>
-          </informalexample>
-
-          struct <structname>mychip</structname> is the type of the chip record.
-        </para>
-
-        <para>
-          In return, the allocated record can be accessed as
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  struct mychip *chip = card->private_data;
-]]>
-            </programlisting>
-          </informalexample>
-
-          With this method, you don't have to allocate twice.
-          The record is released together with the card instance.
-        </para>
-      </section>
-
-      <section id="card-management-chip-specific-allocate-extra">
-        <title>2. Allocating an extra device.</title>
-
-        <para>
-          After allocating a card instance via
-          <function>snd_card_new()</function> (with
-          <constant>0</constant> on the 4th arg), call
-          <function>kzalloc()</function>. 
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  struct snd_card *card;
-  struct mychip *chip;
-  err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
-                     0, &card);
-  .....
-  chip = kzalloc(sizeof(*chip), GFP_KERNEL);
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-          The chip record should have the field to hold the card
-          pointer at least, 
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  struct mychip {
-          struct snd_card *card;
-          ....
-  };
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-          Then, set the card pointer in the returned chip instance.
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  chip->card = card;
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-          Next, initialize the fields, and register this chip
-          record as a low-level device with a specified
-          <parameter>ops</parameter>, 
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static struct snd_device_ops ops = {
-          .dev_free =        snd_mychip_dev_free,
-  };
-  ....
-  snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
-]]>
-            </programlisting>
-          </informalexample>
-
-          <function>snd_mychip_dev_free()</function> is the
-        device-destructor function, which will call the real
-        destructor. 
-        </para>
-
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_mychip_dev_free(struct snd_device *device)
-  {
-          return snd_mychip_free(device->device_data);
-  }
-]]>
-            </programlisting>
-          </informalexample>
-
-          where <function>snd_mychip_free()</function> is the real destructor.
-        </para>
-      </section>
-    </section>
-
-    <section id="card-management-registration">
-      <title>Registration and Release</title>
-      <para>
-        After all components are assigned, register the card instance
-      by calling <function>snd_card_register()</function>. Access
-      to the device files is enabled at this point. That is, before
-      <function>snd_card_register()</function> is called, the
-      components are safely inaccessible from external side. If this
-      call fails, exit the probe function after releasing the card via
-      <function>snd_card_free()</function>. 
-      </para>
-
-      <para>
-        For releasing the card instance, you can call simply
-      <function>snd_card_free()</function>. As mentioned earlier, all
-      components are released automatically by this call. 
-      </para>
-
-      <para>
-      For a device which allows hotplugging, you can use
-      <function>snd_card_free_when_closed</function>.  This one will
-      postpone the destruction until all devices are closed.
-      </para>
-
-    </section>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- PCI Resource Management  -->
-<!-- ****************************************************** -->
-  <chapter id="pci-resource">
-    <title>PCI Resource Management</title>
-
-    <section id="pci-resource-example">
-      <title>Full Code Example</title>
-      <para>
-        In this section, we'll complete the chip-specific constructor,
-      destructor and PCI entries. Example code is shown first,
-      below. 
-
-        <example>
-          <title>PCI Resource Management Example</title>
-          <programlisting>
-<![CDATA[
-  struct mychip {
-          struct snd_card *card;
-          struct pci_dev *pci;
-
-          unsigned long port;
-          int irq;
-  };
-
-  static int snd_mychip_free(struct mychip *chip)
-  {
-          /* disable hardware here if any */
-          .... /* (not implemented in this document) */
-
-          /* release the irq */
-          if (chip->irq >= 0)
-                  free_irq(chip->irq, chip);
-          /* release the I/O ports & memory */
-          pci_release_regions(chip->pci);
-          /* disable the PCI entry */
-          pci_disable_device(chip->pci);
-          /* release the data */
-          kfree(chip);
-          return 0;
-  }
-
-  /* chip-specific constructor */
-  static int snd_mychip_create(struct snd_card *card,
-                               struct pci_dev *pci,
-                               struct mychip **rchip)
-  {
-          struct mychip *chip;
-          int err;
-          static struct snd_device_ops ops = {
-                 .dev_free = snd_mychip_dev_free,
-          };
-
-          *rchip = NULL;
-
-          /* initialize the PCI entry */
-          err = pci_enable_device(pci);
-          if (err < 0)
-                  return err;
-          /* check PCI availability (28bit DMA) */
-          if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
-              pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
-                  printk(KERN_ERR "error to set 28bit mask DMA\n");
-                  pci_disable_device(pci);
-                  return -ENXIO;
-          }
-
-          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
-          if (chip == NULL) {
-                  pci_disable_device(pci);
-                  return -ENOMEM;
-          }
-
-          /* initialize the stuff */
-          chip->card = card;
-          chip->pci = pci;
-          chip->irq = -1;
-
-          /* (1) PCI resource allocation */
-          err = pci_request_regions(pci, "My Chip");
-          if (err < 0) {
-                  kfree(chip);
-                  pci_disable_device(pci);
-                  return err;
-          }
-          chip->port = pci_resource_start(pci, 0);
-          if (request_irq(pci->irq, snd_mychip_interrupt,
-                          IRQF_SHARED, KBUILD_MODNAME, chip)) {
-                  printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
-                  snd_mychip_free(chip);
-                  return -EBUSY;
-          }
-          chip->irq = pci->irq;
-
-          /* (2) initialization of the chip hardware */
-          .... /*   (not implemented in this document) */
-
-          err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
-          if (err < 0) {
-                  snd_mychip_free(chip);
-                  return err;
-          }
-
-          *rchip = chip;
-          return 0;
-  }        
-
-  /* PCI IDs */
-  static struct pci_device_id snd_mychip_ids[] = {
-          { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
-            PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
-          ....
-          { 0, }
-  };
-  MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
-
-  /* pci_driver definition */
-  static struct pci_driver driver = {
-          .name = KBUILD_MODNAME,
-          .id_table = snd_mychip_ids,
-          .probe = snd_mychip_probe,
-          .remove = snd_mychip_remove,
-  };
-
-  /* module initialization */
-  static int __init alsa_card_mychip_init(void)
-  {
-          return pci_register_driver(&driver);
-  }
-
-  /* module clean up */
-  static void __exit alsa_card_mychip_exit(void)
-  {
-          pci_unregister_driver(&driver);
-  }
-
-  module_init(alsa_card_mychip_init)
-  module_exit(alsa_card_mychip_exit)
-
-  EXPORT_NO_SYMBOLS; /* for old kernels only */
-]]>
-          </programlisting>
-        </example>
-      </para>
-    </section>
-
-    <section id="pci-resource-some-haftas">
-      <title>Some Hafta's</title>
-      <para>
-        The allocation of PCI resources is done in the
-      <function>probe()</function> function, and usually an extra
-      <function>xxx_create()</function> function is written for this
-      purpose.
-      </para>
-
-      <para>
-        In the case of PCI devices, you first have to call
-      the <function>pci_enable_device()</function> function before
-      allocating resources. Also, you need to set the proper PCI DMA
-      mask to limit the accessed I/O range. In some cases, you might
-      need to call <function>pci_set_master()</function> function,
-      too.
-      </para>
-
-      <para>
-        Suppose the 28bit mask, and the code to be added would be like:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  err = pci_enable_device(pci);
-  if (err < 0)
-          return err;
-  if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
-      pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
-          printk(KERN_ERR "error to set 28bit mask DMA\n");
-          pci_disable_device(pci);
-          return -ENXIO;
-  }
-  
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-    </section>
-
-    <section id="pci-resource-resource-allocation">
-      <title>Resource Allocation</title>
-      <para>
-        The allocation of I/O ports and irqs is done via standard kernel
-      functions. Unlike ALSA ver.0.5.x., there are no helpers for
-      that. And these resources must be released in the destructor
-      function (see below). Also, on ALSA 0.9.x, you don't need to
-      allocate (pseudo-)DMA for PCI like in ALSA 0.5.x.
-      </para>
-
-      <para>
-        Now assume that the PCI device has an I/O port with 8 bytes
-        and an interrupt. Then struct <structname>mychip</structname> will have the
-        following fields:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct mychip {
-          struct snd_card *card;
-
-          unsigned long port;
-          int irq;
-  };
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        For an I/O port (and also a memory region), you need to have
-      the resource pointer for the standard resource management. For
-      an irq, you have to keep only the irq number (integer). But you
-      need to initialize this number as -1 before actual allocation,
-      since irq 0 is valid. The port address and its resource pointer
-      can be initialized as null by
-      <function>kzalloc()</function> automatically, so you
-      don't have to take care of resetting them. 
-      </para>
-
-      <para>
-        The allocation of an I/O port is done like this:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  err = pci_request_regions(pci, "My Chip");
-  if (err < 0) { 
-          kfree(chip);
-          pci_disable_device(pci);
-          return err;
-  }
-  chip->port = pci_resource_start(pci, 0);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        <!-- obsolete -->
-        It will reserve the I/O port region of 8 bytes of the given
-      PCI device. The returned value, chip-&gt;res_port, is allocated
-      via <function>kmalloc()</function> by
-      <function>request_region()</function>. The pointer must be
-      released via <function>kfree()</function>, but there is a
-      problem with this. This issue will be explained later.
-      </para>
-
-      <para>
-        The allocation of an interrupt source is done like this:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  if (request_irq(pci->irq, snd_mychip_interrupt,
-                  IRQF_SHARED, KBUILD_MODNAME, chip)) {
-          printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
-          snd_mychip_free(chip);
-          return -EBUSY;
-  }
-  chip->irq = pci->irq;
-]]>
-          </programlisting>
-        </informalexample>
-
-        where <function>snd_mychip_interrupt()</function> is the
-      interrupt handler defined <link
-      linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>.
-      Note that chip-&gt;irq should be defined
-      only when <function>request_irq()</function> succeeded.
-      </para>
-
-      <para>
-      On the PCI bus, interrupts can be shared. Thus,
-      <constant>IRQF_SHARED</constant> is used as the interrupt flag of
-      <function>request_irq()</function>. 
-      </para>
-
-      <para>
-        The last argument of <function>request_irq()</function> is the
-      data pointer passed to the interrupt handler. Usually, the
-      chip-specific record is used for that, but you can use what you
-      like, too. 
-      </para>
-
-      <para>
-        I won't give details about the interrupt handler at this
-        point, but at least its appearance can be explained now. The
-        interrupt handler looks usually like the following: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
-  {
-          struct mychip *chip = dev_id;
-          ....
-          return IRQ_HANDLED;
-  }
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        Now let's write the corresponding destructor for the resources
-      above. The role of destructor is simple: disable the hardware
-      (if already activated) and release the resources. So far, we
-      have no hardware part, so the disabling code is not written here. 
-      </para>
-
-      <para>
-        To release the resources, the <quote>check-and-release</quote>
-        method is a safer way. For the interrupt, do like this: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  if (chip->irq >= 0)
-          free_irq(chip->irq, chip);
-]]>
-          </programlisting>
-        </informalexample>
-
-        Since the irq number can start from 0, you should initialize
-        chip-&gt;irq with a negative value (e.g. -1), so that you can
-        check the validity of the irq number as above.
-      </para>
-
-      <para>
-        When you requested I/O ports or memory regions via
-	<function>pci_request_region()</function> or
-	<function>pci_request_regions()</function> like in this example,
-	release the resource(s) using the corresponding function,
-	<function>pci_release_region()</function> or
-	<function>pci_release_regions()</function>.
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  pci_release_regions(chip->pci);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-	When you requested manually via <function>request_region()</function>
-	or <function>request_mem_region</function>, you can release it via
-	<function>release_resource()</function>.  Suppose that you keep
-	the resource pointer returned from <function>request_region()</function>
-	in chip-&gt;res_port, the release procedure looks like:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  release_and_free_resource(chip->res_port);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-      Don't forget to call <function>pci_disable_device()</function>
-      before the end.
-      </para>
-
-      <para>
-        And finally, release the chip-specific record.
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  kfree(chip);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-      We didn't implement the hardware disabling part in the above.
-      If you need to do this, please note that the destructor may be
-      called even before the initialization of the chip is completed.
-      It would be better to have a flag to skip hardware disabling
-      if the hardware was not initialized yet.
-      </para>
-
-      <para>
-      When the chip-data is assigned to the card using
-      <function>snd_device_new()</function> with
-      <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is 
-      called at the last.  That is, it is assured that all other
-      components like PCMs and controls have already been released.
-      You don't have to stop PCMs, etc. explicitly, but just
-      call low-level hardware stopping.
-      </para>
-
-      <para>
-        The management of a memory-mapped region is almost as same as
-        the management of an I/O port. You'll need three fields like
-        the following: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct mychip {
-          ....
-          unsigned long iobase_phys;
-          void __iomem *iobase_virt;
-  };
-]]>
-          </programlisting>
-        </informalexample>
-
-        and the allocation would be like below:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  if ((err = pci_request_regions(pci, "My Chip")) < 0) {
-          kfree(chip);
-          return err;
-  }
-  chip->iobase_phys = pci_resource_start(pci, 0);
-  chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
-                                      pci_resource_len(pci, 0));
-]]>
-          </programlisting>
-        </informalexample>
-        
-        and the corresponding destructor would be:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static int snd_mychip_free(struct mychip *chip)
-  {
-          ....
-          if (chip->iobase_virt)
-                  iounmap(chip->iobase_virt);
-          ....
-          pci_release_regions(chip->pci);
-          ....
-  }
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-    </section>
-
-    <section id="pci-resource-entries">
-      <title>PCI Entries</title>
-      <para>
-        So far, so good. Let's finish the missing PCI
-      stuff. At first, we need a
-      <structname>pci_device_id</structname> table for this
-      chipset. It's a table of PCI vendor/device ID number, and some
-      masks. 
-      </para>
-
-      <para>
-        For example,
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static struct pci_device_id snd_mychip_ids[] = {
-          { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
-            PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
-          ....
-          { 0, }
-  };
-  MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The first and second fields of
-      the <structname>pci_device_id</structname> structure are the vendor and
-      device IDs. If you have no reason to filter the matching
-      devices, you can leave the remaining fields as above. The last
-      field of the <structname>pci_device_id</structname> struct contains
-      private data for this entry. You can specify any value here, for
-      example, to define specific operations for supported device IDs.
-      Such an example is found in the intel8x0 driver. 
-      </para>
-
-      <para>
-        The last entry of this list is the terminator. You must
-      specify this all-zero entry. 
-      </para>
-
-      <para>
-        Then, prepare the <structname>pci_driver</structname> record:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static struct pci_driver driver = {
-          .name = KBUILD_MODNAME,
-          .id_table = snd_mychip_ids,
-          .probe = snd_mychip_probe,
-          .remove = snd_mychip_remove,
-  };
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The <structfield>probe</structfield> and
-      <structfield>remove</structfield> functions have already
-      been defined in the previous sections.
-      The <structfield>name</structfield>
-      field is the name string of this device. Note that you must not
-      use a slash <quote>/</quote> in this string. 
-      </para>
-
-      <para>
-        And at last, the module entries:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static int __init alsa_card_mychip_init(void)
-  {
-          return pci_register_driver(&driver);
-  }
-
-  static void __exit alsa_card_mychip_exit(void)
-  {
-          pci_unregister_driver(&driver);
-  }
-
-  module_init(alsa_card_mychip_init)
-  module_exit(alsa_card_mychip_exit)
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        Note that these module entries are tagged with
-      <parameter>__init</parameter> and 
-      <parameter>__exit</parameter> prefixes.
-      </para>
-
-      <para>
-        Oh, one thing was forgotten. If you have no exported symbols,
-        you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  EXPORT_NO_SYMBOLS;
-]]>
-          </programlisting>
-        </informalexample>
-
-        That's all!
-      </para>
-    </section>
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- PCM Interface  -->
-<!-- ****************************************************** -->
-  <chapter id="pcm-interface">
-    <title>PCM Interface</title>
-
-    <section id="pcm-interface-general">
-      <title>General</title>
-      <para>
-        The PCM middle layer of ALSA is quite powerful and it is only
-      necessary for each driver to implement the low-level functions
-      to access its hardware.
-      </para>
-
-      <para>
-        For accessing to the PCM layer, you need to include
-      <filename>&lt;sound/pcm.h&gt;</filename> first. In addition,
-      <filename>&lt;sound/pcm_params.h&gt;</filename> might be needed
-      if you access to some functions related with hw_param. 
-      </para>
-
-      <para>
-        Each card device can have up to four pcm instances. A pcm
-      instance corresponds to a pcm device file. The limitation of
-      number of instances comes only from the available bit size of
-      the Linux's device numbers. Once when 64bit device number is
-      used, we'll have more pcm instances available. 
-      </para>
-
-      <para>
-        A pcm instance consists of pcm playback and capture streams,
-      and each pcm stream consists of one or more pcm substreams. Some
-      soundcards support multiple playback functions. For example,
-      emu10k1 has a PCM playback of 32 stereo substreams. In this case, at
-      each open, a free substream is (usually) automatically chosen
-      and opened. Meanwhile, when only one substream exists and it was
-      already opened, the successful open will either block
-      or error with <constant>EAGAIN</constant> according to the
-      file open mode. But you don't have to care about such details in your
-      driver. The PCM middle layer will take care of such work.
-      </para>
-    </section>
-
-    <section id="pcm-interface-example">
-      <title>Full Code Example</title>
-      <para>
-      The example code below does not include any hardware access
-      routines but shows only the skeleton, how to build up the PCM
-      interfaces.
-
-        <example>
-          <title>PCM Example Code</title>
-          <programlisting>
-<![CDATA[
-  #include <sound/pcm.h>
-  ....
-
-  /* hardware definition */
-  static struct snd_pcm_hardware snd_mychip_playback_hw = {
-          .info = (SNDRV_PCM_INFO_MMAP |
-                   SNDRV_PCM_INFO_INTERLEAVED |
-                   SNDRV_PCM_INFO_BLOCK_TRANSFER |
-                   SNDRV_PCM_INFO_MMAP_VALID),
-          .formats =          SNDRV_PCM_FMTBIT_S16_LE,
-          .rates =            SNDRV_PCM_RATE_8000_48000,
-          .rate_min =         8000,
-          .rate_max =         48000,
-          .channels_min =     2,
-          .channels_max =     2,
-          .buffer_bytes_max = 32768,
-          .period_bytes_min = 4096,
-          .period_bytes_max = 32768,
-          .periods_min =      1,
-          .periods_max =      1024,
-  };
-
-  /* hardware definition */
-  static struct snd_pcm_hardware snd_mychip_capture_hw = {
-          .info = (SNDRV_PCM_INFO_MMAP |
-                   SNDRV_PCM_INFO_INTERLEAVED |
-                   SNDRV_PCM_INFO_BLOCK_TRANSFER |
-                   SNDRV_PCM_INFO_MMAP_VALID),
-          .formats =          SNDRV_PCM_FMTBIT_S16_LE,
-          .rates =            SNDRV_PCM_RATE_8000_48000,
-          .rate_min =         8000,
-          .rate_max =         48000,
-          .channels_min =     2,
-          .channels_max =     2,
-          .buffer_bytes_max = 32768,
-          .period_bytes_min = 4096,
-          .period_bytes_max = 32768,
-          .periods_min =      1,
-          .periods_max =      1024,
-  };
-
-  /* open callback */
-  static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
-  {
-          struct mychip *chip = snd_pcm_substream_chip(substream);
-          struct snd_pcm_runtime *runtime = substream->runtime;
-
-          runtime->hw = snd_mychip_playback_hw;
-          /* more hardware-initialization will be done here */
-          ....
-          return 0;
-  }
-
-  /* close callback */
-  static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
-  {
-          struct mychip *chip = snd_pcm_substream_chip(substream);
-          /* the hardware-specific codes will be here */
-          ....
-          return 0;
-
-  }
-
-  /* open callback */
-  static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
-  {
-          struct mychip *chip = snd_pcm_substream_chip(substream);
-          struct snd_pcm_runtime *runtime = substream->runtime;
-
-          runtime->hw = snd_mychip_capture_hw;
-          /* more hardware-initialization will be done here */
-          ....
-          return 0;
-  }
-
-  /* close callback */
-  static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
-  {
-          struct mychip *chip = snd_pcm_substream_chip(substream);
-          /* the hardware-specific codes will be here */
-          ....
-          return 0;
-
-  }
-
-  /* hw_params callback */
-  static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
-                               struct snd_pcm_hw_params *hw_params)
-  {
-          return snd_pcm_lib_malloc_pages(substream,
-                                     params_buffer_bytes(hw_params));
-  }
-
-  /* hw_free callback */
-  static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
-  {
-          return snd_pcm_lib_free_pages(substream);
-  }
-
-  /* prepare callback */
-  static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
-  {
-          struct mychip *chip = snd_pcm_substream_chip(substream);
-          struct snd_pcm_runtime *runtime = substream->runtime;
-
-          /* set up the hardware with the current configuration
-           * for example...
-           */
-          mychip_set_sample_format(chip, runtime->format);
-          mychip_set_sample_rate(chip, runtime->rate);
-          mychip_set_channels(chip, runtime->channels);
-          mychip_set_dma_setup(chip, runtime->dma_addr,
-                               chip->buffer_size,
-                               chip->period_size);
-          return 0;
-  }
-
-  /* trigger callback */
-  static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
-                                    int cmd)
-  {
-          switch (cmd) {
-          case SNDRV_PCM_TRIGGER_START:
-                  /* do something to start the PCM engine */
-                  ....
-                  break;
-          case SNDRV_PCM_TRIGGER_STOP:
-                  /* do something to stop the PCM engine */
-                  ....
-                  break;
-          default:
-                  return -EINVAL;
-          }
-  }
-
-  /* pointer callback */
-  static snd_pcm_uframes_t
-  snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
-  {
-          struct mychip *chip = snd_pcm_substream_chip(substream);
-          unsigned int current_ptr;
-
-          /* get the current hardware pointer */
-          current_ptr = mychip_get_hw_pointer(chip);
-          return current_ptr;
-  }
-
-  /* operators */
-  static struct snd_pcm_ops snd_mychip_playback_ops = {
-          .open =        snd_mychip_playback_open,
-          .close =       snd_mychip_playback_close,
-          .ioctl =       snd_pcm_lib_ioctl,
-          .hw_params =   snd_mychip_pcm_hw_params,
-          .hw_free =     snd_mychip_pcm_hw_free,
-          .prepare =     snd_mychip_pcm_prepare,
-          .trigger =     snd_mychip_pcm_trigger,
-          .pointer =     snd_mychip_pcm_pointer,
-  };
-
-  /* operators */
-  static struct snd_pcm_ops snd_mychip_capture_ops = {
-          .open =        snd_mychip_capture_open,
-          .close =       snd_mychip_capture_close,
-          .ioctl =       snd_pcm_lib_ioctl,
-          .hw_params =   snd_mychip_pcm_hw_params,
-          .hw_free =     snd_mychip_pcm_hw_free,
-          .prepare =     snd_mychip_pcm_prepare,
-          .trigger =     snd_mychip_pcm_trigger,
-          .pointer =     snd_mychip_pcm_pointer,
-  };
-
-  /*
-   *  definitions of capture are omitted here...
-   */
-
-  /* create a pcm device */
-  static int snd_mychip_new_pcm(struct mychip *chip)
-  {
-          struct snd_pcm *pcm;
-          int err;
-
-          err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
-          if (err < 0) 
-                  return err;
-          pcm->private_data = chip;
-          strcpy(pcm->name, "My Chip");
-          chip->pcm = pcm;
-          /* set operators */
-          snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
-                          &snd_mychip_playback_ops);
-          snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
-                          &snd_mychip_capture_ops);
-          /* pre-allocation of buffers */
-          /* NOTE: this may fail */
-          snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
-                                                snd_dma_pci_data(chip->pci),
-                                                64*1024, 64*1024);
-          return 0;
-  }
-]]>
-          </programlisting>
-        </example>
-      </para>
-    </section>
-
-    <section id="pcm-interface-constructor">
-      <title>Constructor</title>
-      <para>
-        A pcm instance is allocated by the <function>snd_pcm_new()</function>
-      function. It would be better to create a constructor for pcm,
-      namely, 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static int snd_mychip_new_pcm(struct mychip *chip)
-  {
-          struct snd_pcm *pcm;
-          int err;
-
-          err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
-          if (err < 0) 
-                  return err;
-          pcm->private_data = chip;
-          strcpy(pcm->name, "My Chip");
-          chip->pcm = pcm;
-	  ....
-          return 0;
-  }
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The <function>snd_pcm_new()</function> function takes four
-      arguments. The first argument is the card pointer to which this
-      pcm is assigned, and the second is the ID string. 
-      </para>
-
-      <para>
-        The third argument (<parameter>index</parameter>, 0 in the
-      above) is the index of this new pcm. It begins from zero. If
-      you create more than one pcm instances, specify the
-      different numbers in this argument. For example,
-      <parameter>index</parameter> = 1 for the second PCM device.  
-      </para>
-
-      <para>
-        The fourth and fifth arguments are the number of substreams
-      for playback and capture, respectively. Here 1 is used for
-      both arguments. When no playback or capture substreams are available,
-      pass 0 to the corresponding argument.
-      </para>
-
-      <para>
-        If a chip supports multiple playbacks or captures, you can
-      specify more numbers, but they must be handled properly in
-      open/close, etc. callbacks.  When you need to know which
-      substream you are referring to, then it can be obtained from
-      struct <structname>snd_pcm_substream</structname> data passed to each callback
-      as follows: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_pcm_substream *substream;
-  int index = substream->number;
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        After the pcm is created, you need to set operators for each
-        pcm stream. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
-                  &snd_mychip_playback_ops);
-  snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
-                  &snd_mychip_capture_ops);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The operators are defined typically like this:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static struct snd_pcm_ops snd_mychip_playback_ops = {
-          .open =        snd_mychip_pcm_open,
-          .close =       snd_mychip_pcm_close,
-          .ioctl =       snd_pcm_lib_ioctl,
-          .hw_params =   snd_mychip_pcm_hw_params,
-          .hw_free =     snd_mychip_pcm_hw_free,
-          .prepare =     snd_mychip_pcm_prepare,
-          .trigger =     snd_mychip_pcm_trigger,
-          .pointer =     snd_mychip_pcm_pointer,
-  };
-]]>
-          </programlisting>
-        </informalexample>
-
-        All the callbacks are described in the
-        <link linkend="pcm-interface-operators"><citetitle>
-        Operators</citetitle></link> subsection.
-      </para>
-
-      <para>
-        After setting the operators, you probably will want to
-        pre-allocate the buffer. For the pre-allocation, simply call
-        the following: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
-                                        snd_dma_pci_data(chip->pci),
-                                        64*1024, 64*1024);
-]]>
-          </programlisting>
-        </informalexample>
-
-        It will allocate a buffer up to 64kB as default.
-      Buffer management details will be described in the later section <link
-      linkend="buffer-and-memory"><citetitle>Buffer and Memory
-      Management</citetitle></link>. 
-      </para>
-
-      <para>
-        Additionally, you can set some extra information for this pcm
-        in pcm-&gt;info_flags.
-        The available values are defined as
-        <constant>SNDRV_PCM_INFO_XXX</constant> in
-        <filename>&lt;sound/asound.h&gt;</filename>, which is used for
-        the hardware definition (described later). When your soundchip
-        supports only half-duplex, specify like this: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-    </section>
-
-    <section id="pcm-interface-destructor">
-      <title>... And the Destructor?</title>
-      <para>
-        The destructor for a pcm instance is not always
-      necessary. Since the pcm device will be released by the middle
-      layer code automatically, you don't have to call the destructor
-      explicitly.
-      </para>
-
-      <para>
-        The destructor would be necessary if you created
-        special records internally and needed to release them. In such a
-        case, set the destructor function to
-        pcm-&gt;private_free: 
-
-        <example>
-          <title>PCM Instance with a Destructor</title>
-          <programlisting>
-<![CDATA[
-  static void mychip_pcm_free(struct snd_pcm *pcm)
-  {
-          struct mychip *chip = snd_pcm_chip(pcm);
-          /* free your own data */
-          kfree(chip->my_private_pcm_data);
-          /* do what you like else */
-          ....
-  }
-
-  static int snd_mychip_new_pcm(struct mychip *chip)
-  {
-          struct snd_pcm *pcm;
-          ....
-          /* allocate your own data */
-          chip->my_private_pcm_data = kmalloc(...);
-          /* set the destructor */
-          pcm->private_data = chip;
-          pcm->private_free = mychip_pcm_free;
-          ....
-  }
-]]>
-          </programlisting>
-        </example>
-      </para>
-    </section>
-
-    <section id="pcm-interface-runtime">
-      <title>Runtime Pointer - The Chest of PCM Information</title>
-	<para>
-	  When the PCM substream is opened, a PCM runtime instance is
-	allocated and assigned to the substream. This pointer is
-	accessible via <constant>substream-&gt;runtime</constant>.
-	This runtime pointer holds most information you need
-	to control the PCM: the copy of hw_params and sw_params configurations, the buffer
-	pointers, mmap records, spinlocks, etc.
-	</para>
-
-	<para>
-	The definition of runtime instance is found in
-	<filename>&lt;sound/pcm.h&gt;</filename>.  Here are
-       the contents of this file:
-          <informalexample>
-            <programlisting>
-<![CDATA[
-struct _snd_pcm_runtime {
-	/* -- Status -- */
-	struct snd_pcm_substream *trigger_master;
-	snd_timestamp_t trigger_tstamp;	/* trigger timestamp */
-	int overrange;
-	snd_pcm_uframes_t avail_max;
-	snd_pcm_uframes_t hw_ptr_base;	/* Position at buffer restart */
-	snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
-
-	/* -- HW params -- */
-	snd_pcm_access_t access;	/* access mode */
-	snd_pcm_format_t format;	/* SNDRV_PCM_FORMAT_* */
-	snd_pcm_subformat_t subformat;	/* subformat */
-	unsigned int rate;		/* rate in Hz */
-	unsigned int channels;		/* channels */
-	snd_pcm_uframes_t period_size;	/* period size */
-	unsigned int periods;		/* periods */
-	snd_pcm_uframes_t buffer_size;	/* buffer size */
-	unsigned int tick_time;		/* tick time */
-	snd_pcm_uframes_t min_align;	/* Min alignment for the format */
-	size_t byte_align;
-	unsigned int frame_bits;
-	unsigned int sample_bits;
-	unsigned int info;
-	unsigned int rate_num;
-	unsigned int rate_den;
-
-	/* -- SW params -- */
-	struct timespec tstamp_mode;	/* mmap timestamp is updated */
-  	unsigned int period_step;
-	unsigned int sleep_min;		/* min ticks to sleep */
-	snd_pcm_uframes_t start_threshold;
-	snd_pcm_uframes_t stop_threshold;
-	snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
-						noise is nearest than this */
-	snd_pcm_uframes_t silence_size;	/* Silence filling size */
-	snd_pcm_uframes_t boundary;	/* pointers wrap point */
-
-	snd_pcm_uframes_t silenced_start;
-	snd_pcm_uframes_t silenced_size;
-
-	snd_pcm_sync_id_t sync;		/* hardware synchronization ID */
-
-	/* -- mmap -- */
-	volatile struct snd_pcm_mmap_status *status;
-	volatile struct snd_pcm_mmap_control *control;
-	atomic_t mmap_count;
-
-	/* -- locking / scheduling -- */
-	spinlock_t lock;
-	wait_queue_head_t sleep;
-	struct timer_list tick_timer;
-	struct fasync_struct *fasync;
-
-	/* -- private section -- */
-	void *private_data;
-	void (*private_free)(struct snd_pcm_runtime *runtime);
-
-	/* -- hardware description -- */
-	struct snd_pcm_hardware hw;
-	struct snd_pcm_hw_constraints hw_constraints;
-
-	/* -- timer -- */
-	unsigned int timer_resolution;	/* timer resolution */
-
-	/* -- DMA -- */           
-	unsigned char *dma_area;	/* DMA area */
-	dma_addr_t dma_addr;		/* physical bus address (not accessible from main CPU) */
-	size_t dma_bytes;		/* size of DMA area */
-
-	struct snd_dma_buffer *dma_buffer_p;	/* allocated buffer */
-
-#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
-	/* -- OSS things -- */
-	struct snd_pcm_oss_runtime oss;
-#endif
-};
-]]>
-            </programlisting>
-          </informalexample>
-	</para>
-
-	<para>
-	  For the operators (callbacks) of each sound driver, most of
-	these records are supposed to be read-only.  Only the PCM
-	middle-layer changes / updates them.  The exceptions are
-	the hardware description (hw) DMA buffer information and the
-	private data.  Besides, if you use the standard buffer allocation
-	method via <function>snd_pcm_lib_malloc_pages()</function>,
-	you don't need to set the DMA buffer information by yourself.
-	</para>
-
-	<para>
-	In the sections below, important records are explained.
-	</para>
-
-	<section id="pcm-interface-runtime-hw">
-	<title>Hardware Description</title>
-	<para>
-	  The hardware descriptor (struct <structname>snd_pcm_hardware</structname>)
-	contains the definitions of the fundamental hardware
-	configuration.  Above all, you'll need to define this in
-	<link linkend="pcm-interface-operators-open-callback"><citetitle>
-	the open callback</citetitle></link>.
-	Note that the runtime instance holds the copy of the
-	descriptor, not the pointer to the existing descriptor.  That
-	is, in the open callback, you can modify the copied descriptor
-	(<constant>runtime-&gt;hw</constant>) as you need.  For example, if the maximum
-	number of channels is 1 only on some chip models, you can
-	still use the same hardware descriptor and change the
-	channels_max later:
-          <informalexample>
-            <programlisting>
-<![CDATA[
-          struct snd_pcm_runtime *runtime = substream->runtime;
-          ...
-          runtime->hw = snd_mychip_playback_hw; /* common definition */
-          if (chip->model == VERY_OLD_ONE)
-                  runtime->hw.channels_max = 1;
-]]>
-            </programlisting>
-          </informalexample>
-	</para>
-
-	<para>
-	  Typically, you'll have a hardware descriptor as below:
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static struct snd_pcm_hardware snd_mychip_playback_hw = {
-          .info = (SNDRV_PCM_INFO_MMAP |
-                   SNDRV_PCM_INFO_INTERLEAVED |
-                   SNDRV_PCM_INFO_BLOCK_TRANSFER |
-                   SNDRV_PCM_INFO_MMAP_VALID),
-          .formats =          SNDRV_PCM_FMTBIT_S16_LE,
-          .rates =            SNDRV_PCM_RATE_8000_48000,
-          .rate_min =         8000,
-          .rate_max =         48000,
-          .channels_min =     2,
-          .channels_max =     2,
-          .buffer_bytes_max = 32768,
-          .period_bytes_min = 4096,
-          .period_bytes_max = 32768,
-          .periods_min =      1,
-          .periods_max =      1024,
-  };
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-	<itemizedlist>
-	<listitem><para>
-          The <structfield>info</structfield> field contains the type and
-        capabilities of this pcm. The bit flags are defined in
-        <filename>&lt;sound/asound.h&gt;</filename> as
-        <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
-        have to specify whether the mmap is supported and which
-        interleaved format is supported.
-        When the hardware supports mmap, add the
-        <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
-        hardware supports the interleaved or the non-interleaved
-        formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
-        <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
-        be set, respectively. If both are supported, you can set both,
-        too. 
-        </para>
-
-        <para>
-          In the above example, <constant>MMAP_VALID</constant> and
-        <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap
-        mode. Usually both are set. Of course,
-        <constant>MMAP_VALID</constant> is set only if the mmap is
-        really supported. 
-        </para>
-
-        <para>
-          The other possible flags are
-        <constant>SNDRV_PCM_INFO_PAUSE</constant> and
-        <constant>SNDRV_PCM_INFO_RESUME</constant>. The
-        <constant>PAUSE</constant> bit means that the pcm supports the
-        <quote>pause</quote> operation, while the
-        <constant>RESUME</constant> bit means that the pcm supports
-        the full <quote>suspend/resume</quote> operation.
-	If the <constant>PAUSE</constant> flag is set,
-	the <structfield>trigger</structfield> callback below
-        must handle the corresponding (pause push/release) commands.
-	The suspend/resume trigger commands can be defined even without
-	the <constant>RESUME</constant> flag.  See <link
-	linkend="power-management"><citetitle>
-	Power Management</citetitle></link> section for details.
-        </para>
-
-	<para>
-	  When the PCM substreams can be synchronized (typically,
-	synchronized start/stop of a playback and a capture streams),
-	you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
-	too.  In this case, you'll need to check the linked-list of
-	PCM substreams in the trigger callback.  This will be
-	described in the later section.
-	</para>
-	</listitem>
-
-	<listitem>
-        <para>
-          <structfield>formats</structfield> field contains the bit-flags
-        of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
-        If the hardware supports more than one format, give all or'ed
-        bits.  In the example above, the signed 16bit little-endian
-        format is specified.
-        </para>
-	</listitem>
-
-	<listitem>
-        <para>
-        <structfield>rates</structfield> field contains the bit-flags of
-        supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
-        When the chip supports continuous rates, pass
-        <constant>CONTINUOUS</constant> bit additionally.
-        The pre-defined rate bits are provided only for typical
-	rates. If your chip supports unconventional rates, you need to add
-        the <constant>KNOT</constant> bit and set up the hardware
-        constraint manually (explained later).
-        </para>
-	</listitem>
-
-	<listitem>
-	<para>
-	<structfield>rate_min</structfield> and
-	<structfield>rate_max</structfield> define the minimum and
-	maximum sample rate.  This should correspond somehow to
-	<structfield>rates</structfield> bits.
-	</para>
-	</listitem>
-
-	<listitem>
-	<para>
-	<structfield>channel_min</structfield> and
-	<structfield>channel_max</structfield> 
-	define, as you might already expected, the minimum and maximum
-	number of channels.
-	</para>
-	</listitem>
-
-	<listitem>
-	<para>
-	<structfield>buffer_bytes_max</structfield> defines the
-	maximum buffer size in bytes.  There is no
-	<structfield>buffer_bytes_min</structfield> field, since
-	it can be calculated from the minimum period size and the
-	minimum number of periods.
-	Meanwhile, <structfield>period_bytes_min</structfield> and
-	define the minimum and maximum size of the period in bytes.
-	<structfield>periods_max</structfield> and
-	<structfield>periods_min</structfield> define the maximum and
-	minimum number of periods in the buffer.
-        </para>
-
-	<para>
-	The <quote>period</quote> is a term that corresponds to
-	a fragment in the OSS world. The period defines the size at
-	which a PCM interrupt is generated. This size strongly
-	depends on the hardware. 
-	Generally, the smaller period size will give you more
-	interrupts, that is, more controls. 
-	In the case of capture, this size defines the input latency.
-	On the other hand, the whole buffer size defines the
-	output latency for the playback direction.
-	</para>
-	</listitem>
-
-	<listitem>
-	<para>
-	There is also a field <structfield>fifo_size</structfield>.
-	This specifies the size of the hardware FIFO, but currently it
-	is neither used in the driver nor in the alsa-lib.  So, you
-	can ignore this field.
-	</para>
-	</listitem>
-	</itemizedlist>
-	</para>
-	</section>
-
-	<section id="pcm-interface-runtime-config">
-	<title>PCM Configurations</title>
-	<para>
-	Ok, let's go back again to the PCM runtime records.
-	The most frequently referred records in the runtime instance are
-	the PCM configurations.
-	The PCM configurations are stored in the runtime instance
-	after the application sends <type>hw_params</type> data via
-	alsa-lib.  There are many fields copied from hw_params and
-	sw_params structs.  For example,
-	<structfield>format</structfield> holds the format type
-	chosen by the application.  This field contains the enum value
-	<constant>SNDRV_PCM_FORMAT_XXX</constant>.
-	</para>
-
-	<para>
-	One thing to be noted is that the configured buffer and period
-	sizes are stored in <quote>frames</quote> in the runtime.
-        In the ALSA world, 1 frame = channels * samples-size.
-	For conversion between frames and bytes, you can use the
-	<function>frames_to_bytes()</function> and
-          <function>bytes_to_frames()</function> helper functions. 
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  period_bytes = frames_to_bytes(runtime, runtime->period_size);
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-	<para>
-	Also, many software parameters (sw_params) are
-	stored in frames, too.  Please check the type of the field.
-	<type>snd_pcm_uframes_t</type> is for the frames as unsigned
-	integer while <type>snd_pcm_sframes_t</type> is for the frames
-	as signed integer.
-	</para>
-	</section>
-
-	<section id="pcm-interface-runtime-dma">
-	<title>DMA Buffer Information</title>
-	<para>
-	The DMA buffer is defined by the following four fields,
-	<structfield>dma_area</structfield>,
-	<structfield>dma_addr</structfield>,
-	<structfield>dma_bytes</structfield> and
-	<structfield>dma_private</structfield>.
-	The <structfield>dma_area</structfield> holds the buffer
-	pointer (the logical address).  You can call
-	<function>memcpy</function> from/to 
-	this pointer.  Meanwhile, <structfield>dma_addr</structfield>
-	holds the physical address of the buffer.  This field is
-	specified only when the buffer is a linear buffer.
-	<structfield>dma_bytes</structfield> holds the size of buffer
-	in bytes.  <structfield>dma_private</structfield> is used for
-	the ALSA DMA allocator.
-	</para>
-
-	<para>
-	If you use a standard ALSA function,
-	<function>snd_pcm_lib_malloc_pages()</function>, for
-	allocating the buffer, these fields are set by the ALSA middle
-	layer, and you should <emphasis>not</emphasis> change them by
-	yourself.  You can read them but not write them.
-	On the other hand, if you want to allocate the buffer by
-	yourself, you'll need to manage it in hw_params callback.
-	At least, <structfield>dma_bytes</structfield> is mandatory.
-	<structfield>dma_area</structfield> is necessary when the
-	buffer is mmapped.  If your driver doesn't support mmap, this
-	field is not necessary.  <structfield>dma_addr</structfield>
-	is also optional.  You can use
-	<structfield>dma_private</structfield> as you like, too.
-	</para>
-	</section>
-
-	<section id="pcm-interface-runtime-status">
-	<title>Running Status</title>
-	<para>
-	The running status can be referred via <constant>runtime-&gt;status</constant>.
-	This is the pointer to the struct <structname>snd_pcm_mmap_status</structname>
-	record.  For example, you can get the current DMA hardware
-	pointer via <constant>runtime-&gt;status-&gt;hw_ptr</constant>.
-	</para>
-
-	<para>
-	The DMA application pointer can be referred via
-	<constant>runtime-&gt;control</constant>, which points to the
-	struct <structname>snd_pcm_mmap_control</structname> record.
-	However, accessing directly to this value is not recommended.
-	</para>
-	</section>
-
-	<section id="pcm-interface-runtime-private">
-	<title>Private Data</title> 
-	<para>
-	You can allocate a record for the substream and store it in
-	<constant>runtime-&gt;private_data</constant>.  Usually, this
-	is done in
-	<link linkend="pcm-interface-operators-open-callback"><citetitle>
-	the open callback</citetitle></link>.
-	Don't mix this with <constant>pcm-&gt;private_data</constant>.
-	The <constant>pcm-&gt;private_data</constant> usually points to the
-	chip instance assigned statically at the creation of PCM, while the 
-	<constant>runtime-&gt;private_data</constant> points to a dynamic
-	data structure created at the PCM open callback.
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_xxx_open(struct snd_pcm_substream *substream)
-  {
-          struct my_pcm_data *data;
-          ....
-          data = kmalloc(sizeof(*data), GFP_KERNEL);
-          substream->runtime->private_data = data;
-          ....
-  }
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-          The allocated object must be released in
-	<link linkend="pcm-interface-operators-open-callback"><citetitle>
-	the close callback</citetitle></link>.
-        </para>
-	</section>
-
-    </section>
-
-    <section id="pcm-interface-operators">
-      <title>Operators</title>
-      <para>
-        OK, now let me give details about each pcm callback
-      (<parameter>ops</parameter>). In general, every callback must
-      return 0 if successful, or a negative error number
-      such as <constant>-EINVAL</constant>. To choose an appropriate
-      error number, it is advised to check what value other parts of
-      the kernel return when the same kind of request fails.
-      </para>
-
-      <para>
-        The callback function takes at least the argument with
-        <structname>snd_pcm_substream</structname> pointer. To retrieve
-        the chip record from the given substream instance, you can use the
-        following macro. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  int xxx() {
-          struct mychip *chip = snd_pcm_substream_chip(substream);
-          ....
-  }
-]]>
-          </programlisting>
-        </informalexample>
-
-	The macro reads <constant>substream-&gt;private_data</constant>,
-	which is a copy of <constant>pcm-&gt;private_data</constant>.
-	You can override the former if you need to assign different data
-	records per PCM substream.  For example, the cmi8330 driver assigns
-	different private_data for playback and capture directions,
-	because it uses two different codecs (SB- and AD-compatible) for
-	different directions.
-      </para>
-
-      <section id="pcm-interface-operators-open-callback">
-        <title>open callback</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_xxx_open(struct snd_pcm_substream *substream);
-]]>
-            </programlisting>
-          </informalexample>
-
-          This is called when a pcm substream is opened.
-        </para>
-
-        <para>
-          At least, here you have to initialize the runtime-&gt;hw
-          record. Typically, this is done by like this: 
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_xxx_open(struct snd_pcm_substream *substream)
-  {
-          struct mychip *chip = snd_pcm_substream_chip(substream);
-          struct snd_pcm_runtime *runtime = substream->runtime;
-
-          runtime->hw = snd_mychip_playback_hw;
-          return 0;
-  }
-]]>
-            </programlisting>
-          </informalexample>
-
-          where <parameter>snd_mychip_playback_hw</parameter> is the
-          pre-defined hardware description.
-	</para>
-
-	<para>
-	You can allocate a private data in this callback, as described
-	in <link linkend="pcm-interface-runtime-private"><citetitle>
-	Private Data</citetitle></link> section.
-	</para>
-
-	<para>
-	If the hardware configuration needs more constraints, set the
-	hardware constraints here, too.
-	See <link linkend="pcm-interface-constraints"><citetitle>
-	Constraints</citetitle></link> for more details.
-	</para>
-      </section>
-
-      <section id="pcm-interface-operators-close-callback">
-        <title>close callback</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_xxx_close(struct snd_pcm_substream *substream);
-]]>
-            </programlisting>
-          </informalexample>
-
-          Obviously, this is called when a pcm substream is closed.
-        </para>
-
-        <para>
-          Any private instance for a pcm substream allocated in the
-          open callback will be released here. 
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_xxx_close(struct snd_pcm_substream *substream)
-  {
-          ....
-          kfree(substream->runtime->private_data);
-          ....
-  }
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-      </section>
-
-      <section id="pcm-interface-operators-ioctl-callback">
-        <title>ioctl callback</title>
-        <para>
-          This is used for any special call to pcm ioctls. But
-        usually you can pass a generic ioctl callback, 
-        <function>snd_pcm_lib_ioctl</function>.
-        </para>
-      </section>
-
-      <section id="pcm-interface-operators-hw-params-callback">
-        <title>hw_params callback</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
-                               struct snd_pcm_hw_params *hw_params);
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-          This is called when the hardware parameter
-        (<structfield>hw_params</structfield>) is set
-        up by the application, 
-        that is, once when the buffer size, the period size, the
-        format, etc. are defined for the pcm substream. 
-        </para>
-
-        <para>
-          Many hardware setups should be done in this callback,
-        including the allocation of buffers. 
-        </para>
-
-        <para>
-          Parameters to be initialized are retrieved by
-          <function>params_xxx()</function> macros. To allocate
-          buffer, you can call a helper function, 
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
-]]>
-            </programlisting>
-          </informalexample>
-
-          <function>snd_pcm_lib_malloc_pages()</function> is available
-	  only when the DMA buffers have been pre-allocated.
-	  See the section <link
-	  linkend="buffer-and-memory-buffer-types"><citetitle>
-	  Buffer Types</citetitle></link> for more details.
-        </para>
-
-        <para>
-          Note that this and <structfield>prepare</structfield> callbacks
-        may be called multiple times per initialization.
-        For example, the OSS emulation may
-        call these callbacks at each change via its ioctl. 
-        </para>
-
-        <para>
-          Thus, you need to be careful not to allocate the same buffers
-        many times, which will lead to memory leaks!  Calling the
-        helper function above many times is OK. It will release the
-        previous buffer automatically when it was already allocated. 
-        </para>
-
-        <para>
-          Another note is that this callback is non-atomic
-        (schedulable) as default, i.e. when no
-	<structfield>nonatomic</structfield> flag set.
-	This is important, because the
-        <structfield>trigger</structfield> callback 
-        is atomic (non-schedulable). That is, mutexes or any
-        schedule-related functions are not available in
-        <structfield>trigger</structfield> callback.
-	Please see the subsection
-	<link linkend="pcm-interface-atomicity"><citetitle>
-	Atomicity</citetitle></link> for details.
-        </para>
-      </section>
-
-      <section id="pcm-interface-operators-hw-free-callback">
-        <title>hw_free callback</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-          This is called to release the resources allocated via
-          <structfield>hw_params</structfield>. For example, releasing the
-          buffer via 
-          <function>snd_pcm_lib_malloc_pages()</function> is done by
-          calling the following: 
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  snd_pcm_lib_free_pages(substream);
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-          This function is always called before the close callback is called.
-          Also, the callback may be called multiple times, too.
-          Keep track whether the resource was already released. 
-        </para>
-      </section>
-
-      <section id="pcm-interface-operators-prepare-callback">
-       <title>prepare callback</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_xxx_prepare(struct snd_pcm_substream *substream);
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-          This callback is called when the pcm is
-        <quote>prepared</quote>. You can set the format type, sample
-        rate, etc. here. The difference from
-        <structfield>hw_params</structfield> is that the 
-        <structfield>prepare</structfield> callback will be called each
-        time 
-        <function>snd_pcm_prepare()</function> is called, i.e. when
-        recovering after underruns, etc. 
-        </para>
-
-        <para>
-	Note that this callback is now non-atomic.
-	You can use schedule-related functions safely in this callback.
-        </para>
-
-        <para>
-          In this and the following callbacks, you can refer to the
-        values via the runtime record,
-        substream-&gt;runtime.
-        For example, to get the current
-        rate, format or channels, access to
-        runtime-&gt;rate,
-        runtime-&gt;format or
-        runtime-&gt;channels, respectively. 
-        The physical address of the allocated buffer is set to
-	runtime-&gt;dma_area.  The buffer and period sizes are
-	in runtime-&gt;buffer_size and runtime-&gt;period_size,
-	respectively.
-        </para>
-
-        <para>
-          Be careful that this callback will be called many times at
-        each setup, too. 
-        </para>
-      </section>
-
-      <section id="pcm-interface-operators-trigger-callback">
-        <title>trigger callback</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
-]]>
-            </programlisting>
-          </informalexample>
-
-          This is called when the pcm is started, stopped or paused.
-        </para>
-
-        <para>
-          Which action is specified in the second argument,
-          <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
-          <filename>&lt;sound/pcm.h&gt;</filename>. At least,
-          the <constant>START</constant> and <constant>STOP</constant>
-          commands must be defined in this callback. 
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  switch (cmd) {
-  case SNDRV_PCM_TRIGGER_START:
-          /* do something to start the PCM engine */
-          break;
-  case SNDRV_PCM_TRIGGER_STOP:
-          /* do something to stop the PCM engine */
-          break;
-  default:
-          return -EINVAL;
-  }
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-          When the pcm supports the pause operation (given in the info
-        field of the hardware table), the <constant>PAUSE_PUSH</constant>
-        and <constant>PAUSE_RELEASE</constant> commands must be
-        handled here, too. The former is the command to pause the pcm,
-        and the latter to restart the pcm again. 
-        </para>
-
-        <para>
-          When the pcm supports the suspend/resume operation,
-	regardless of full or partial suspend/resume support,
-        the <constant>SUSPEND</constant> and <constant>RESUME</constant>
-        commands must be handled, too.
-        These commands are issued when the power-management status is
-        changed.  Obviously, the <constant>SUSPEND</constant> and
-        <constant>RESUME</constant> commands
-        suspend and resume the pcm substream, and usually, they
-        are identical to the <constant>STOP</constant> and
-        <constant>START</constant> commands, respectively.
-	  See the <link linkend="power-management"><citetitle>
-	Power Management</citetitle></link> section for details.
-        </para>
-
-        <para>
-          As mentioned, this callback is atomic as default unless
-	  <structfield>nonatomic</structfield> flag set, and
-	  you cannot call functions which may sleep.
-	  The trigger callback should be as minimal as possible,
-	  just really triggering the DMA.  The other stuff should be
-	  initialized hw_params and prepare callbacks properly
-	  beforehand.
-        </para>
-      </section>
-
-      <section id="pcm-interface-operators-pointer-callback">
-        <title>pointer callback</title>
-        <para>
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
-]]>
-            </programlisting>
-          </informalexample>
-
-          This callback is called when the PCM middle layer inquires
-        the current hardware position on the buffer. The position must
-        be returned in frames,
-        ranging from 0 to buffer_size - 1.
-        </para>
-
-        <para>
-          This is called usually from the buffer-update routine in the
-        pcm middle layer, which is invoked when
-        <function>snd_pcm_period_elapsed()</function> is called in the
-        interrupt routine. Then the pcm middle layer updates the
-        position and calculates the available space, and wakes up the
-        sleeping poll threads, etc. 
-        </para>
-
-        <para>
-          This callback is also atomic as default.
-        </para>
-      </section>
-
-      <section id="pcm-interface-operators-copy-silence">
-        <title>copy and silence callbacks</title>
-        <para>
-          These callbacks are not mandatory, and can be omitted in
-        most cases. These callbacks are used when the hardware buffer
-        cannot be in the normal memory space. Some chips have their
-        own buffer on the hardware which is not mappable. In such a
-        case, you have to transfer the data manually from the memory
-        buffer to the hardware buffer. Or, if the buffer is
-        non-contiguous on both physical and virtual memory spaces,
-        these callbacks must be defined, too. 
-        </para>
-
-        <para>
-          If these two callbacks are defined, copy and set-silence
-        operations are done by them. The detailed will be described in
-        the later section <link
-        linkend="buffer-and-memory"><citetitle>Buffer and Memory
-        Management</citetitle></link>. 
-        </para>
-      </section>
-
-      <section id="pcm-interface-operators-ack">
-        <title>ack callback</title>
-        <para>
-          This callback is also not mandatory. This callback is called
-        when the appl_ptr is updated in read or write operations.
-        Some drivers like emu10k1-fx and cs46xx need to track the
-	current appl_ptr for the internal buffer, and this callback
-	is useful only for such a purpose.
-	</para>
-	<para>
-	  This callback is atomic as default.
-	</para>
-      </section>
-
-      <section id="pcm-interface-operators-page-callback">
-        <title>page callback</title>
-
-        <para>
-          This callback is optional too. This callback is used
-        mainly for non-contiguous buffers. The mmap calls this
-        callback to get the page address. Some examples will be
-        explained in the later section <link
-        linkend="buffer-and-memory"><citetitle>Buffer and Memory
-        Management</citetitle></link>, too. 
-        </para>
-      </section>
-    </section>
-
-    <section id="pcm-interface-interrupt-handler">
-      <title>Interrupt Handler</title>
-      <para>
-        The rest of pcm stuff is the PCM interrupt handler. The
-      role of PCM interrupt handler in the sound driver is to update
-      the buffer position and to tell the PCM middle layer when the
-      buffer position goes across the prescribed period size. To
-      inform this, call the <function>snd_pcm_period_elapsed()</function>
-      function. 
-      </para>
-
-      <para>
-        There are several types of sound chips to generate the interrupts.
-      </para>
-
-      <section id="pcm-interface-interrupt-handler-boundary">
-        <title>Interrupts at the period (fragment) boundary</title>
-        <para>
-          This is the most frequently found type:  the hardware
-        generates an interrupt at each period boundary.
-	In this case, you can call
-        <function>snd_pcm_period_elapsed()</function> at each 
-        interrupt. 
-        </para>
-
-        <para>
-          <function>snd_pcm_period_elapsed()</function> takes the
-        substream pointer as its argument. Thus, you need to keep the
-        substream pointer accessible from the chip instance. For
-        example, define substream field in the chip record to hold the
-        current running substream pointer, and set the pointer value
-        at open callback (and reset at close callback). 
-        </para>
-
-        <para>
-          If you acquire a spinlock in the interrupt handler, and the
-        lock is used in other pcm callbacks, too, then you have to
-        release the lock before calling
-        <function>snd_pcm_period_elapsed()</function>, because
-        <function>snd_pcm_period_elapsed()</function> calls other pcm
-        callbacks inside. 
-        </para>
-
-        <para>
-          Typical code would be like:
-
-          <example>
-	    <title>Interrupt Handler Case #1</title>
-            <programlisting>
-<![CDATA[
-  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
-  {
-          struct mychip *chip = dev_id;
-          spin_lock(&chip->lock);
-          ....
-          if (pcm_irq_invoked(chip)) {
-                  /* call updater, unlock before it */
-                  spin_unlock(&chip->lock);
-                  snd_pcm_period_elapsed(chip->substream);
-                  spin_lock(&chip->lock);
-                  /* acknowledge the interrupt if necessary */
-          }
-          ....
-          spin_unlock(&chip->lock);
-          return IRQ_HANDLED;
-  }
-]]>
-            </programlisting>
-          </example>
-        </para>
-      </section>
-
-      <section id="pcm-interface-interrupt-handler-timer">
-        <title>High frequency timer interrupts</title>
-        <para>
-	This happens when the hardware doesn't generate interrupts
-        at the period boundary but issues timer interrupts at a fixed
-        timer rate (e.g. es1968 or ymfpci drivers). 
-        In this case, you need to check the current hardware
-        position and accumulate the processed sample length at each
-        interrupt.  When the accumulated size exceeds the period
-        size, call 
-        <function>snd_pcm_period_elapsed()</function> and reset the
-        accumulator. 
-        </para>
-
-        <para>
-          Typical code would be like the following.
-
-          <example>
-	    <title>Interrupt Handler Case #2</title>
-            <programlisting>
-<![CDATA[
-  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
-  {
-          struct mychip *chip = dev_id;
-          spin_lock(&chip->lock);
-          ....
-          if (pcm_irq_invoked(chip)) {
-                  unsigned int last_ptr, size;
-                  /* get the current hardware pointer (in frames) */
-                  last_ptr = get_hw_ptr(chip);
-                  /* calculate the processed frames since the
-                   * last update
-                   */
-                  if (last_ptr < chip->last_ptr)
-                          size = runtime->buffer_size + last_ptr 
-                                   - chip->last_ptr; 
-                  else
-                          size = last_ptr - chip->last_ptr;
-                  /* remember the last updated point */
-                  chip->last_ptr = last_ptr;
-                  /* accumulate the size */
-                  chip->size += size;
-                  /* over the period boundary? */
-                  if (chip->size >= runtime->period_size) {
-                          /* reset the accumulator */
-                          chip->size %= runtime->period_size;
-                          /* call updater */
-                          spin_unlock(&chip->lock);
-                          snd_pcm_period_elapsed(substream);
-                          spin_lock(&chip->lock);
-                  }
-                  /* acknowledge the interrupt if necessary */
-          }
-          ....
-          spin_unlock(&chip->lock);
-          return IRQ_HANDLED;
-  }
-]]>
-            </programlisting>
-          </example>
-        </para>
-      </section>
-
-      <section id="pcm-interface-interrupt-handler-both">
-        <title>On calling <function>snd_pcm_period_elapsed()</function></title>
-        <para>
-          In both cases, even if more than one period are elapsed, you
-        don't have to call
-        <function>snd_pcm_period_elapsed()</function> many times. Call
-        only once. And the pcm layer will check the current hardware
-        pointer and update to the latest status. 
-        </para>
-      </section>
-    </section>
-
-    <section id="pcm-interface-atomicity">
-      <title>Atomicity</title>
-      <para>
-      One of the most important (and thus difficult to debug) problems
-      in kernel programming are race conditions.
-      In the Linux kernel, they are usually avoided via spin-locks, mutexes
-      or semaphores.  In general, if a race condition can happen
-      in an interrupt handler, it has to be managed atomically, and you
-      have to use a spinlock to protect the critical session. If the
-      critical section is not in interrupt handler code and
-      if taking a relatively long time to execute is acceptable, you
-      should use mutexes or semaphores instead.
-      </para>
-
-      <para>
-      As already seen, some pcm callbacks are atomic and some are
-      not.  For example, the <parameter>hw_params</parameter> callback is
-      non-atomic, while <parameter>trigger</parameter> callback is
-      atomic.  This means, the latter is called already in a spinlock
-      held by the PCM middle layer. Please take this atomicity into
-      account when you choose a locking scheme in the callbacks.
-      </para>
-
-      <para>
-      In the atomic callbacks, you cannot use functions which may call
-      <function>schedule</function> or go to
-      <function>sleep</function>.  Semaphores and mutexes can sleep,
-      and hence they cannot be used inside the atomic callbacks
-      (e.g. <parameter>trigger</parameter> callback).
-      To implement some delay in such a callback, please use
-      <function>udelay()</function> or <function>mdelay()</function>.
-      </para>
-
-      <para>
-      All three atomic callbacks (trigger, pointer, and ack) are
-      called with local interrupts disabled.
-      </para>
-
-      <para>
-      The recent changes in PCM core code, however, allow all PCM
-      operations to be non-atomic.  This assumes that the all caller
-      sides are in non-atomic contexts.  For example, the function
-      <function>snd_pcm_period_elapsed()</function> is called
-      typically from the interrupt handler.  But, if you set up the
-      driver to use a threaded interrupt handler, this call can be in
-      non-atomic context, too.  In such a case, you can set
-      <structfield>nonatomic</structfield> filed of
-      <structname>snd_pcm</structname> object after creating it.
-      When this flag is set, mutex and rwsem are used internally in
-      the PCM core instead of spin and rwlocks, so that you can call
-      all PCM functions safely in a non-atomic context.
-      </para>
-
-    </section>
-    <section id="pcm-interface-constraints">
-      <title>Constraints</title>
-      <para>
-        If your chip supports unconventional sample rates, or only the
-      limited samples, you need to set a constraint for the
-      condition. 
-      </para>
-
-      <para>
-        For example, in order to restrict the sample rates in the some
-        supported values, use
-	<function>snd_pcm_hw_constraint_list()</function>.
-	You need to call this function in the open callback.
-
-        <example>
-	  <title>Example of Hardware Constraints</title>
-          <programlisting>
-<![CDATA[
-  static unsigned int rates[] =
-          {4000, 10000, 22050, 44100};
-  static struct snd_pcm_hw_constraint_list constraints_rates = {
-          .count = ARRAY_SIZE(rates),
-          .list = rates,
-          .mask = 0,
-  };
-
-  static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
-  {
-          int err;
-          ....
-          err = snd_pcm_hw_constraint_list(substream->runtime, 0,
-                                           SNDRV_PCM_HW_PARAM_RATE,
-                                           &constraints_rates);
-          if (err < 0)
-                  return err;
-          ....
-  }
-]]>
-          </programlisting>
-        </example>
-      </para>
-
-      <para>
-        There are many different constraints.
-        Look at <filename>sound/pcm.h</filename> for a complete list.
-        You can even define your own constraint rules.
-        For example, let's suppose my_chip can manage a substream of 1 channel
-        if and only if the format is S16_LE, otherwise it supports any format
-        specified in the <structname>snd_pcm_hardware</structname> structure (or in any
-        other constraint_list). You can build a rule like this:
-
-        <example>
-	  <title>Example of Hardware Constraints for Channels</title>
-	  <programlisting>
-<![CDATA[
-  static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
-                                        struct snd_pcm_hw_rule *rule)
-  {
-          struct snd_interval *c = hw_param_interval(params,
-                        SNDRV_PCM_HW_PARAM_CHANNELS);
-          struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
-          struct snd_interval ch;
-
-          snd_interval_any(&ch);
-          if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
-                  ch.min = ch.max = 1;
-                  ch.integer = 1;
-                  return snd_interval_refine(c, &ch);
-          }
-          return 0;
-  }
-]]>
-          </programlisting>
-        </example>
-      </para>
- 
-      <para>
-        Then you need to call this function to add your rule:
-
-       <informalexample>
-	 <programlisting>
-<![CDATA[
-  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
-                      hw_rule_channels_by_format, NULL,
-                      SNDRV_PCM_HW_PARAM_FORMAT, -1);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The rule function is called when an application sets the PCM
-	format, and it refines the number of channels accordingly.
-        But an application may set the number of channels before
-	setting the format. Thus you also need to define the inverse rule:
-
-       <example>
-	 <title>Example of Hardware Constraints for Formats</title>
-	 <programlisting>
-<![CDATA[
-  static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
-                                        struct snd_pcm_hw_rule *rule)
-  {
-          struct snd_interval *c = hw_param_interval(params,
-                SNDRV_PCM_HW_PARAM_CHANNELS);
-          struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
-          struct snd_mask fmt;
-
-          snd_mask_any(&fmt);    /* Init the struct */
-          if (c->min < 2) {
-                  fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
-                  return snd_mask_refine(f, &fmt);
-          }
-          return 0;
-  }
-]]>
-          </programlisting>
-        </example>
-      </para>
-
-      <para>
-      ...and in the open callback:
-       <informalexample>
-	 <programlisting>
-<![CDATA[
-  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
-                      hw_rule_format_by_channels, NULL,
-                      SNDRV_PCM_HW_PARAM_CHANNELS, -1);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        I won't give more details here, rather I
-        would like to say, <quote>Luke, use the source.</quote>
-      </para>
-    </section>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Control Interface  -->
-<!-- ****************************************************** -->
-  <chapter id="control-interface">
-    <title>Control Interface</title>
-
-    <section id="control-interface-general">
-      <title>General</title>
-      <para>
-        The control interface is used widely for many switches,
-      sliders, etc. which are accessed from user-space. Its most
-      important use is the mixer interface. In other words, since ALSA
-      0.9.x, all the mixer stuff is implemented on the control kernel API.
-      </para>
-
-      <para>
-        ALSA has a well-defined AC97 control module. If your chip
-      supports only the AC97 and nothing else, you can skip this
-      section. 
-      </para>
-
-      <para>
-        The control API is defined in
-      <filename>&lt;sound/control.h&gt;</filename>.
-      Include this file if you want to add your own controls.
-      </para>
-    </section>
-
-    <section id="control-interface-definition">
-      <title>Definition of Controls</title>
-      <para>
-        To create a new control, you need to define the
-	following three
-      callbacks: <structfield>info</structfield>,
-      <structfield>get</structfield> and
-      <structfield>put</structfield>. Then, define a
-      struct <structname>snd_kcontrol_new</structname> record, such as: 
-
-        <example>
-	  <title>Definition of a Control</title>
-          <programlisting>
-<![CDATA[
-  static struct snd_kcontrol_new my_control = {
-          .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
-          .name = "PCM Playback Switch",
-          .index = 0,
-          .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
-          .private_value = 0xffff,
-          .info = my_control_info,
-          .get = my_control_get,
-          .put = my_control_put
-  };
-]]>
-          </programlisting>
-        </example>
-      </para>
-
-      <para>
-        The <structfield>iface</structfield> field specifies the control
-      type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
-      is usually <constant>MIXER</constant>.
-      Use <constant>CARD</constant> for global controls that are not
-      logically part of the mixer.
-      If the control is closely associated with some specific device on
-      the sound card, use <constant>HWDEP</constant>,
-      <constant>PCM</constant>, <constant>RAWMIDI</constant>,
-      <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
-      specify the device number with the
-      <structfield>device</structfield> and
-      <structfield>subdevice</structfield> fields.
-      </para>
-
-      <para>
-        The <structfield>name</structfield> is the name identifier
-      string. Since ALSA 0.9.x, the control name is very important,
-      because its role is classified from its name. There are
-      pre-defined standard control names. The details are described in
-      the <link linkend="control-interface-control-names"><citetitle>
-      Control Names</citetitle></link> subsection.
-      </para>
-
-      <para>
-        The <structfield>index</structfield> field holds the index number
-      of this control. If there are several different controls with
-      the same name, they can be distinguished by the index
-      number. This is the case when 
-      several codecs exist on the card. If the index is zero, you can
-      omit the definition above. 
-      </para>
-
-      <para>
-        The <structfield>access</structfield> field contains the access
-      type of this control. Give the combination of bit masks,
-      <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
-      The details will be explained in
-      the <link linkend="control-interface-access-flags"><citetitle>
-      Access Flags</citetitle></link> subsection.
-      </para>
-
-      <para>
-        The <structfield>private_value</structfield> field contains
-      an arbitrary long integer value for this record. When using
-      the generic <structfield>info</structfield>,
-      <structfield>get</structfield> and
-      <structfield>put</structfield> callbacks, you can pass a value 
-      through this field. If several small numbers are necessary, you can
-      combine them in bitwise. Or, it's possible to give a pointer
-      (casted to unsigned long) of some record to this field, too. 
-      </para>
-
-      <para>
-      The <structfield>tlv</structfield> field can be used to provide
-      metadata about the control; see the
-      <link linkend="control-interface-tlv">
-      <citetitle>Metadata</citetitle></link> subsection.
-      </para>
-
-      <para>
-        The other three are
-	<link linkend="control-interface-callbacks"><citetitle>
-	callback functions</citetitle></link>.
-      </para>
-    </section>
-
-    <section id="control-interface-control-names">
-      <title>Control Names</title>
-      <para>
-        There are some standards to define the control names. A
-      control is usually defined from the three parts as
-      <quote>SOURCE DIRECTION FUNCTION</quote>. 
-      </para>
-
-      <para>
-        The first, <constant>SOURCE</constant>, specifies the source
-      of the control, and is a string such as <quote>Master</quote>,
-      <quote>PCM</quote>, <quote>CD</quote> and
-      <quote>Line</quote>. There are many pre-defined sources. 
-      </para>
-
-      <para>
-        The second, <constant>DIRECTION</constant>, is one of the
-      following strings according to the direction of the control:
-      <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
-      Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
-      be omitted, meaning both playback and capture directions. 
-      </para>
-
-      <para>
-        The third, <constant>FUNCTION</constant>, is one of the
-      following strings according to the function of the control:
-      <quote>Switch</quote>, <quote>Volume</quote> and
-      <quote>Route</quote>. 
-      </para>
-
-      <para>
-        The example of control names are, thus, <quote>Master Capture
-      Switch</quote> or <quote>PCM Playback Volume</quote>. 
-      </para>
-
-      <para>
-        There are some exceptions:
-      </para>
-
-      <section id="control-interface-control-names-global">
-        <title>Global capture and playback</title>
-        <para>
-          <quote>Capture Source</quote>, <quote>Capture Switch</quote>
-        and <quote>Capture Volume</quote> are used for the global
-        capture (input) source, switch and volume. Similarly,
-        <quote>Playback Switch</quote> and <quote>Playback
-        Volume</quote> are used for the global output gain switch and
-        volume. 
-        </para>
-      </section>
-
-      <section id="control-interface-control-names-tone">
-        <title>Tone-controls</title>
-        <para>
-          tone-control switch and volumes are specified like
-        <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
-        Switch</quote>, <quote>Tone Control - Bass</quote>,
-        <quote>Tone Control - Center</quote>.  
-        </para>
-      </section>
-
-      <section id="control-interface-control-names-3d">
-        <title>3D controls</title>
-        <para>
-          3D-control switches and volumes are specified like <quote>3D
-        Control - XXX</quote>, e.g. <quote>3D Control -
-        Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
-        Control - Space</quote>. 
-        </para>
-      </section>
-
-      <section id="control-interface-control-names-mic">
-        <title>Mic boost</title>
-        <para>
-          Mic-boost switch is set as <quote>Mic Boost</quote> or
-        <quote>Mic Boost (6dB)</quote>. 
-        </para>
-
-        <para>
-          More precise information can be found in
-        <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
-        </para>
-      </section>
-    </section>
-
-    <section id="control-interface-access-flags">
-      <title>Access Flags</title>
-
-      <para>
-      The access flag is the bitmask which specifies the access type
-      of the given control.  The default access type is
-      <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>, 
-      which means both read and write are allowed to this control.
-      When the access flag is omitted (i.e. = 0), it is
-      considered as <constant>READWRITE</constant> access as default. 
-      </para>
-
-      <para>
-      When the control is read-only, pass
-      <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
-      In this case, you don't have to define
-      the <structfield>put</structfield> callback.
-      Similarly, when the control is write-only (although it's a rare
-      case), you can use the <constant>WRITE</constant> flag instead, and
-      you don't need the <structfield>get</structfield> callback.
-      </para>
-
-      <para>
-      If the control value changes frequently (e.g. the VU meter),
-      <constant>VOLATILE</constant> flag should be given.  This means
-      that the control may be changed without
-      <link linkend="control-interface-change-notification"><citetitle>
-      notification</citetitle></link>. Applications should poll such
-      a control constantly.
-      </para>
-
-      <para>
-      When the control is inactive, set
-      the <constant>INACTIVE</constant> flag, too.
-      There are <constant>LOCK</constant> and
-      <constant>OWNER</constant> flags to change the write
-      permissions.
-      </para>
-
-    </section>
-
-    <section id="control-interface-callbacks">
-      <title>Callbacks</title>
-
-      <section id="control-interface-callbacks-info">
-        <title>info callback</title>
-        <para>
-          The <structfield>info</structfield> callback is used to get
-        detailed information on this control. This must store the
-        values of the given struct <structname>snd_ctl_elem_info</structname>
-        object. For example, for a boolean control with a single
-        element: 
-
-          <example>
-	    <title>Example of info callback</title>
-            <programlisting>
-<![CDATA[
-  static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
-                          struct snd_ctl_elem_info *uinfo)
-  {
-          uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
-          uinfo->count = 1;
-          uinfo->value.integer.min = 0;
-          uinfo->value.integer.max = 1;
-          return 0;
-  }
-]]>
-            </programlisting>
-          </example>
-        </para>
-
-        <para>
-          The <structfield>type</structfield> field specifies the type
-        of the control. There are <constant>BOOLEAN</constant>,
-        <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
-        <constant>BYTES</constant>, <constant>IEC958</constant> and
-        <constant>INTEGER64</constant>. The
-        <structfield>count</structfield> field specifies the 
-        number of elements in this control. For example, a stereo
-        volume would have count = 2. The
-        <structfield>value</structfield> field is a union, and 
-        the values stored are depending on the type. The boolean and
-        integer types are identical. 
-        </para>
-
-        <para>
-          The enumerated type is a bit different from others.  You'll
-          need to set the string for the currently given item index. 
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
-                          struct snd_ctl_elem_info *uinfo)
-  {
-          static char *texts[4] = {
-                  "First", "Second", "Third", "Fourth"
-          };
-          uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
-          uinfo->count = 1;
-          uinfo->value.enumerated.items = 4;
-          if (uinfo->value.enumerated.item > 3)
-                  uinfo->value.enumerated.item = 3;
-          strcpy(uinfo->value.enumerated.name,
-                 texts[uinfo->value.enumerated.item]);
-          return 0;
-  }
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-	  The above callback can be simplified with a helper function,
-	  <function>snd_ctl_enum_info</function>.  The final code
-	  looks like below.
-	  (You can pass ARRAY_SIZE(texts) instead of 4 in the third
-	   argument; it's a matter of taste.)
-
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
-                          struct snd_ctl_elem_info *uinfo)
-  {
-          static char *texts[4] = {
-                  "First", "Second", "Third", "Fourth"
-          };
-          return snd_ctl_enum_info(uinfo, 1, 4, texts);
-  }
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-	  Some common info callbacks are available for your convenience:
-	<function>snd_ctl_boolean_mono_info()</function> and
-	<function>snd_ctl_boolean_stereo_info()</function>.
-	Obviously, the former is an info callback for a mono channel
-	boolean item, just like <function>snd_myctl_mono_info</function>
-	above, and the latter is for a stereo channel boolean item.
-	</para>
-
-      </section>
-
-      <section id="control-interface-callbacks-get">
-        <title>get callback</title>
-
-        <para>
-          This callback is used to read the current value of the
-        control and to return to user-space. 
-        </para>
-
-        <para>
-          For example,
-
-          <example>
-	    <title>Example of get callback</title>
-            <programlisting>
-<![CDATA[
-  static int snd_myctl_get(struct snd_kcontrol *kcontrol,
-                           struct snd_ctl_elem_value *ucontrol)
-  {
-          struct mychip *chip = snd_kcontrol_chip(kcontrol);
-          ucontrol->value.integer.value[0] = get_some_value(chip);
-          return 0;
-  }
-]]>
-            </programlisting>
-          </example>
-        </para>
-
-        <para>
-	The <structfield>value</structfield> field depends on 
-        the type of control as well as on the info callback.  For example,
-	the sb driver uses this field to store the register offset,
-        the bit-shift and the bit-mask.  The
-        <structfield>private_value</structfield> field is set as follows:
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  .private_value = reg | (shift << 16) | (mask << 24)
-]]>
-            </programlisting>
-          </informalexample>
-	and is retrieved in callbacks like
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
-                                    struct snd_ctl_elem_value *ucontrol)
-  {
-          int reg = kcontrol->private_value & 0xff;
-          int shift = (kcontrol->private_value >> 16) & 0xff;
-          int mask = (kcontrol->private_value >> 24) & 0xff;
-          ....
-  }
-]]>
-            </programlisting>
-          </informalexample>
-	</para>
-
-	<para>
-	In the <structfield>get</structfield> callback,
-	you have to fill all the elements if the
-        control has more than one elements,
-        i.e. <structfield>count</structfield> &gt; 1.
-	In the example above, we filled only one element
-        (<structfield>value.integer.value[0]</structfield>) since it's
-        assumed as <structfield>count</structfield> = 1.
-        </para>
-      </section>
-
-      <section id="control-interface-callbacks-put">
-        <title>put callback</title>
-
-        <para>
-          This callback is used to write a value from user-space.
-        </para>
-
-        <para>
-          For example,
-
-          <example>
-	    <title>Example of put callback</title>
-            <programlisting>
-<![CDATA[
-  static int snd_myctl_put(struct snd_kcontrol *kcontrol,
-                           struct snd_ctl_elem_value *ucontrol)
-  {
-          struct mychip *chip = snd_kcontrol_chip(kcontrol);
-          int changed = 0;
-          if (chip->current_value !=
-               ucontrol->value.integer.value[0]) {
-                  change_current_value(chip,
-                              ucontrol->value.integer.value[0]);
-                  changed = 1;
-          }
-          return changed;
-  }
-]]>
-            </programlisting>
-          </example>
-
-          As seen above, you have to return 1 if the value is
-        changed. If the value is not changed, return 0 instead. 
-	If any fatal error happens, return a negative error code as
-        usual.
-        </para>
-
-        <para>
-	As in the <structfield>get</structfield> callback,
-	when the control has more than one elements,
-	all elements must be evaluated in this callback, too.
-        </para>
-      </section>
-
-      <section id="control-interface-callbacks-all">
-        <title>Callbacks are not atomic</title>
-        <para>
-          All these three callbacks are basically not atomic.
-        </para>
-      </section>
-    </section>
-
-    <section id="control-interface-constructor">
-      <title>Constructor</title>
-      <para>
-        When everything is ready, finally we can create a new
-      control. To create a control, there are two functions to be
-      called, <function>snd_ctl_new1()</function> and
-      <function>snd_ctl_add()</function>. 
-      </para>
-
-      <para>
-        In the simplest way, you can do like this:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
-  if (err < 0)
-          return err;
-]]>
-          </programlisting>
-        </informalexample>
-
-        where <parameter>my_control</parameter> is the
-      struct <structname>snd_kcontrol_new</structname> object defined above, and chip
-      is the object pointer to be passed to
-      kcontrol-&gt;private_data 
-      which can be referred to in callbacks. 
-      </para>
-
-      <para>
-        <function>snd_ctl_new1()</function> allocates a new
-      <structname>snd_kcontrol</structname> instance,
-      and <function>snd_ctl_add</function> assigns the given
-      control component to the card. 
-      </para>
-    </section>
-
-    <section id="control-interface-change-notification">
-      <title>Change Notification</title>
-      <para>
-        If you need to change and update a control in the interrupt
-      routine, you can call <function>snd_ctl_notify()</function>. For
-      example, 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
-]]>
-          </programlisting>
-        </informalexample>
-
-        This function takes the card pointer, the event-mask, and the
-      control id pointer for the notification. The event-mask
-      specifies the types of notification, for example, in the above
-      example, the change of control values is notified.
-      The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
-      to be notified.
-      You can find some examples in <filename>es1938.c</filename> or
-      <filename>es1968.c</filename> for hardware volume interrupts. 
-      </para>
-    </section>
-
-    <section id="control-interface-tlv">
-      <title>Metadata</title>
-      <para>
-      To provide information about the dB values of a mixer control, use
-      on of the <constant>DECLARE_TLV_xxx</constant> macros from
-      <filename>&lt;sound/tlv.h&gt;</filename> to define a variable
-      containing this information, set the<structfield>tlv.p
-      </structfield> field to point to this variable, and include the
-      <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
-      <structfield>access</structfield> field; like this:
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
-
-  static struct snd_kcontrol_new my_control = {
-          ...
-          .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
-                    SNDRV_CTL_ELEM_ACCESS_TLV_READ,
-          ...
-          .tlv.p = db_scale_my_control,
-  };
-]]>
-        </programlisting>
-      </informalexample>
-      </para>
-
-      <para>
-      The <function>DECLARE_TLV_DB_SCALE</function> macro defines
-      information about a mixer control where each step in the control's
-      value changes the dB value by a constant dB amount.
-      The first parameter is the name of the variable to be defined.
-      The second parameter is the minimum value, in units of 0.01 dB.
-      The third parameter is the step size, in units of 0.01 dB.
-      Set the fourth parameter to 1 if the minimum value actually mutes
-      the control.
-      </para>
-
-      <para>
-      The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
-      information about a mixer control where the control's value affects
-      the output linearly.
-      The first parameter is the name of the variable to be defined.
-      The second parameter is the minimum value, in units of 0.01 dB.
-      The third parameter is the maximum value, in units of 0.01 dB.
-      If the minimum value mutes the control, set the second parameter to
-      <constant>TLV_DB_GAIN_MUTE</constant>.
-      </para>
-    </section>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- API for AC97 Codec  -->
-<!-- ****************************************************** -->
-  <chapter id="api-ac97">
-    <title>API for AC97 Codec</title>
-
-    <section>
-      <title>General</title>
-      <para>
-        The ALSA AC97 codec layer is a well-defined one, and you don't
-      have to write much code to control it. Only low-level control
-      routines are necessary. The AC97 codec API is defined in
-      <filename>&lt;sound/ac97_codec.h&gt;</filename>. 
-      </para>
-    </section>
-
-    <section id="api-ac97-example">
-      <title>Full Code Example</title>
-      <para>
-          <example>
-	    <title>Example of AC97 Interface</title>
-            <programlisting>
-<![CDATA[
-  struct mychip {
-          ....
-          struct snd_ac97 *ac97;
-          ....
-  };
-
-  static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
-                                             unsigned short reg)
-  {
-          struct mychip *chip = ac97->private_data;
-          ....
-          /* read a register value here from the codec */
-          return the_register_value;
-  }
-
-  static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
-                                   unsigned short reg, unsigned short val)
-  {
-          struct mychip *chip = ac97->private_data;
-          ....
-          /* write the given register value to the codec */
-  }
-
-  static int snd_mychip_ac97(struct mychip *chip)
-  {
-          struct snd_ac97_bus *bus;
-          struct snd_ac97_template ac97;
-          int err;
-          static struct snd_ac97_bus_ops ops = {
-                  .write = snd_mychip_ac97_write,
-                  .read = snd_mychip_ac97_read,
-          };
-
-          err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
-          if (err < 0)
-                  return err;
-          memset(&ac97, 0, sizeof(ac97));
-          ac97.private_data = chip;
-          return snd_ac97_mixer(bus, &ac97, &chip->ac97);
-  }
-
-]]>
-          </programlisting>
-        </example>
-      </para>
-    </section>
-
-    <section id="api-ac97-constructor">
-      <title>Constructor</title>
-      <para>
-        To create an ac97 instance, first call <function>snd_ac97_bus</function>
-      with an <type>ac97_bus_ops_t</type> record with callback functions.
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_ac97_bus *bus;
-  static struct snd_ac97_bus_ops ops = {
-        .write = snd_mychip_ac97_write,
-        .read = snd_mychip_ac97_read,
-  };
-
-  snd_ac97_bus(card, 0, &ops, NULL, &pbus);
-]]>
-          </programlisting>
-        </informalexample>
-
-      The bus record is shared among all belonging ac97 instances.
-      </para>
-
-      <para>
-      And then call <function>snd_ac97_mixer()</function> with an
-      struct <structname>snd_ac97_template</structname>
-      record together with the bus pointer created above.
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_ac97_template ac97;
-  int err;
-
-  memset(&ac97, 0, sizeof(ac97));
-  ac97.private_data = chip;
-  snd_ac97_mixer(bus, &ac97, &chip->ac97);
-]]>
-          </programlisting>
-        </informalexample>
-
-        where chip-&gt;ac97 is a pointer to a newly created
-        <type>ac97_t</type> instance.
-        In this case, the chip pointer is set as the private data, so that
-        the read/write callback functions can refer to this chip instance.
-        This instance is not necessarily stored in the chip
-	record.  If you need to change the register values from the
-        driver, or need the suspend/resume of ac97 codecs, keep this
-        pointer to pass to the corresponding functions.
-      </para>
-    </section>
-
-    <section id="api-ac97-callbacks">
-      <title>Callbacks</title>
-      <para>
-        The standard callbacks are <structfield>read</structfield> and
-      <structfield>write</structfield>. Obviously they 
-      correspond to the functions for read and write accesses to the
-      hardware low-level codes. 
-      </para>
-
-      <para>
-        The <structfield>read</structfield> callback returns the
-        register value specified in the argument. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
-                                             unsigned short reg)
-  {
-          struct mychip *chip = ac97->private_data;
-          ....
-          return the_register_value;
-  }
-]]>
-          </programlisting>
-        </informalexample>
-
-        Here, the chip can be cast from ac97-&gt;private_data.
-      </para>
-
-      <para>
-        Meanwhile, the <structfield>write</structfield> callback is
-        used to set the register value. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
-                       unsigned short reg, unsigned short val)
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-      These callbacks are non-atomic like the control API callbacks.
-      </para>
-
-      <para>
-        There are also other callbacks:
-      <structfield>reset</structfield>,
-      <structfield>wait</structfield> and
-      <structfield>init</structfield>. 
-      </para>
-
-      <para>
-        The <structfield>reset</structfield> callback is used to reset
-      the codec. If the chip requires a special kind of reset, you can
-      define this callback. 
-      </para>
-
-      <para>
-        The <structfield>wait</structfield> callback is used to
-      add some waiting time in the standard initialization of the codec. If the
-      chip requires the extra waiting time, define this callback. 
-      </para>
-
-      <para>
-        The <structfield>init</structfield> callback is used for
-      additional initialization of the codec.
-      </para>
-    </section>
-
-    <section id="api-ac97-updating-registers">
-      <title>Updating Registers in The Driver</title>
-      <para>
-        If you need to access to the codec from the driver, you can
-      call the following functions:
-      <function>snd_ac97_write()</function>,
-      <function>snd_ac97_read()</function>,
-      <function>snd_ac97_update()</function> and
-      <function>snd_ac97_update_bits()</function>. 
-      </para>
-
-      <para>
-        Both <function>snd_ac97_write()</function> and
-        <function>snd_ac97_update()</function> functions are used to
-        set a value to the given register
-        (<constant>AC97_XXX</constant>). The difference between them is
-        that <function>snd_ac97_update()</function> doesn't write a
-        value if the given value has been already set, while
-        <function>snd_ac97_write()</function> always rewrites the
-        value. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_ac97_write(ac97, AC97_MASTER, 0x8080);
-  snd_ac97_update(ac97, AC97_MASTER, 0x8080);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        <function>snd_ac97_read()</function> is used to read the value
-        of the given register. For example, 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  value = snd_ac97_read(ac97, AC97_MASTER);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        <function>snd_ac97_update_bits()</function> is used to update
-        some bits in the given register.  
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_ac97_update_bits(ac97, reg, mask, value);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        Also, there is a function to change the sample rate (of a
-        given register such as
-        <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
-        DRA is supported by the codec:
-        <function>snd_ac97_set_rate()</function>. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The following registers are available to set the rate:
-      <constant>AC97_PCM_MIC_ADC_RATE</constant>,
-      <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
-      <constant>AC97_PCM_LR_ADC_RATE</constant>,
-      <constant>AC97_SPDIF</constant>. When
-      <constant>AC97_SPDIF</constant> is specified, the register is
-      not really changed but the corresponding IEC958 status bits will
-      be updated. 
-      </para>
-    </section>
-
-    <section id="api-ac97-clock-adjustment">
-      <title>Clock Adjustment</title>
-      <para>
-        In some chips, the clock of the codec isn't 48000 but using a
-      PCI clock (to save a quartz!). In this case, change the field
-      bus-&gt;clock to the corresponding
-      value. For example, intel8x0 
-      and es1968 drivers have their own function to read from the clock.
-      </para>
-    </section>
-
-    <section id="api-ac97-proc-files">
-      <title>Proc Files</title>
-      <para>
-        The ALSA AC97 interface will create a proc file such as
-      <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
-      <filename>ac97#0-0+regs</filename>. You can refer to these files to
-      see the current status and registers of the codec. 
-      </para>
-    </section>
-
-    <section id="api-ac97-multiple-codecs">
-      <title>Multiple Codecs</title>
-      <para>
-        When there are several codecs on the same card, you need to
-      call <function>snd_ac97_mixer()</function> multiple times with
-      ac97.num=1 or greater. The <structfield>num</structfield> field
-      specifies the codec number. 
-      </para>
-
-      <para>
-        If you set up multiple codecs, you either need to write
-      different callbacks for each codec or check
-      ac97-&gt;num in the callback routines. 
-      </para>
-    </section>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- MIDI (MPU401-UART) Interface  -->
-<!-- ****************************************************** -->
-  <chapter id="midi-interface">
-    <title>MIDI (MPU401-UART) Interface</title>
-
-    <section id="midi-interface-general">
-      <title>General</title>
-      <para>
-        Many soundcards have built-in MIDI (MPU401-UART)
-      interfaces. When the soundcard supports the standard MPU401-UART
-      interface, most likely you can use the ALSA MPU401-UART API. The
-      MPU401-UART API is defined in
-      <filename>&lt;sound/mpu401.h&gt;</filename>. 
-      </para>
-
-      <para>
-        Some soundchips have a similar but slightly different
-      implementation of mpu401 stuff. For example, emu10k1 has its own
-      mpu401 routines. 
-      </para>
-    </section>
-
-    <section id="midi-interface-constructor">
-      <title>Constructor</title>
-      <para>
-        To create a rawmidi object, call
-      <function>snd_mpu401_uart_new()</function>. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_rawmidi *rmidi;
-  snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
-                      irq, &rmidi);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The first argument is the card pointer, and the second is the
-      index of this component. You can create up to 8 rawmidi
-      devices. 
-      </para>
-
-      <para>
-        The third argument is the type of the hardware,
-      <constant>MPU401_HW_XXX</constant>. If it's not a special one,
-      you can use <constant>MPU401_HW_MPU401</constant>. 
-      </para>
-
-      <para>
-        The 4th argument is the I/O port address. Many
-      backward-compatible MPU401 have an I/O port such as 0x330. Or, it
-      might be a part of its own PCI I/O region. It depends on the
-      chip design. 
-      </para>
-
-      <para>
-	The 5th argument is a bitflag for additional information.
-        When the I/O port address above is part of the PCI I/O
-      region, the MPU401 I/O port might have been already allocated
-      (reserved) by the driver itself. In such a case, pass a bit flag
-      <constant>MPU401_INFO_INTEGRATED</constant>,
-      and the mpu401-uart layer will allocate the I/O ports by itself. 
-      </para>
-
-	<para>
-	When the controller supports only the input or output MIDI stream,
-	pass the <constant>MPU401_INFO_INPUT</constant> or
-	<constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
-	Then the rawmidi instance is created as a single stream.
-	</para>
-
-	<para>
-	<constant>MPU401_INFO_MMIO</constant> bitflag is used to change
-	the access method to MMIO (via readb and writeb) instead of
-	iob and outb. In this case, you have to pass the iomapped address
-	to <function>snd_mpu401_uart_new()</function>.
-	</para>
-
-	<para>
-	When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
-	stream isn't checked in the default interrupt handler.  The driver
-	needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
-	by itself to start processing the output stream in the irq handler.
-	</para>
-
-	<para>
-	If the MPU-401 interface shares its interrupt with the other logical
-	devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant>
-	(see <link linkend="midi-interface-interrupt-handler"><citetitle>
-	below</citetitle></link>).
-	</para>
-
-      <para>
-        Usually, the port address corresponds to the command port and
-        port + 1 corresponds to the data port. If not, you may change
-        the <structfield>cport</structfield> field of
-        struct <structname>snd_mpu401</structname> manually 
-        afterward. However, <structname>snd_mpu401</structname> pointer is not
-        returned explicitly by
-        <function>snd_mpu401_uart_new()</function>. You need to cast
-        rmidi-&gt;private_data to
-        <structname>snd_mpu401</structname> explicitly, 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_mpu401 *mpu;
-  mpu = rmidi->private_data;
-]]>
-          </programlisting>
-        </informalexample>
-
-        and reset the cport as you like:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  mpu->cport = my_own_control_port;
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-	The 6th argument specifies the ISA irq number that will be
-	allocated.  If no interrupt is to be allocated (because your
-	code is already allocating a shared interrupt, or because the
-	device does not use interrupts), pass -1 instead.
-	For a MPU-401 device without an interrupt, a polling timer
-	will be used instead.
-      </para>
-    </section>
-
-    <section id="midi-interface-interrupt-handler">
-      <title>Interrupt Handler</title>
-      <para>
-        When the interrupt is allocated in
-      <function>snd_mpu401_uart_new()</function>, an exclusive ISA
-      interrupt handler is automatically used, hence you don't have
-      anything else to do than creating the mpu401 stuff.  Otherwise, you
-      have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call
-      <function>snd_mpu401_uart_interrupt()</function> explicitly from your
-      own interrupt handler when it has determined that a UART interrupt
-      has occurred.
-      </para>
-
-      <para>
-        In this case, you need to pass the private_data of the
-        returned rawmidi object from
-        <function>snd_mpu401_uart_new()</function> as the second
-        argument of <function>snd_mpu401_uart_interrupt()</function>. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-    </section>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- RawMIDI Interface  -->
-<!-- ****************************************************** -->
-  <chapter id="rawmidi-interface">
-    <title>RawMIDI Interface</title>
-
-    <section id="rawmidi-interface-overview">
-      <title>Overview</title>
-
-      <para>
-      The raw MIDI interface is used for hardware MIDI ports that can
-      be accessed as a byte stream.  It is not used for synthesizer
-      chips that do not directly understand MIDI.
-      </para>
-
-      <para>
-      ALSA handles file and buffer management.  All you have to do is
-      to write some code to move data between the buffer and the
-      hardware.
-      </para>
-
-      <para>
-      The rawmidi API is defined in
-      <filename>&lt;sound/rawmidi.h&gt;</filename>.
-      </para>
-    </section>
-
-    <section id="rawmidi-interface-constructor">
-      <title>Constructor</title>
-
-      <para>
-      To create a rawmidi device, call the
-      <function>snd_rawmidi_new</function> function:
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_rawmidi *rmidi;
-  err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
-  if (err < 0)
-          return err;
-  rmidi->private_data = chip;
-  strcpy(rmidi->name, "My MIDI");
-  rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
-                      SNDRV_RAWMIDI_INFO_INPUT |
-                      SNDRV_RAWMIDI_INFO_DUPLEX;
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-      The first argument is the card pointer, the second argument is
-      the ID string.
-      </para>
-
-      <para>
-      The third argument is the index of this component.  You can
-      create up to 8 rawmidi devices.
-      </para>
-
-      <para>
-      The fourth and fifth arguments are the number of output and
-      input substreams, respectively, of this device (a substream is
-      the equivalent of a MIDI port).
-      </para>
-
-      <para>
-      Set the <structfield>info_flags</structfield> field to specify
-      the capabilities of the device.
-      Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
-      at least one output port,
-      <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
-      least one input port,
-      and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
-      can handle output and input at the same time.
-      </para>
-
-      <para>
-      After the rawmidi device is created, you need to set the
-      operators (callbacks) for each substream.  There are helper
-      functions to set the operators for all the substreams of a device:
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
-  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-      The operators are usually defined like this:
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static struct snd_rawmidi_ops snd_mymidi_output_ops = {
-          .open =    snd_mymidi_output_open,
-          .close =   snd_mymidi_output_close,
-          .trigger = snd_mymidi_output_trigger,
-  };
-]]>
-          </programlisting>
-        </informalexample>
-      These callbacks are explained in the <link
-      linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
-      section.
-      </para>
-
-      <para>
-      If there are more than one substream, you should give a
-      unique name to each of them:
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_rawmidi_substream *substream;
-  list_for_each_entry(substream,
-                      &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
-                      list {
-          sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
-  }
-  /* same for SNDRV_RAWMIDI_STREAM_INPUT */
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-    </section>
-
-    <section id="rawmidi-interface-callbacks">
-      <title>Callbacks</title>
-
-      <para>
-      In all the callbacks, the private data that you've set for the
-      rawmidi device can be accessed as
-      substream-&gt;rmidi-&gt;private_data.
-      <!-- <code> isn't available before DocBook 4.3 -->
-      </para>
-
-      <para>
-      If there is more than one port, your callbacks can determine the
-      port index from the struct snd_rawmidi_substream data passed to each
-      callback:
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_rawmidi_substream *substream;
-  int index = substream->number;
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <section id="rawmidi-interface-op-open">
-      <title><function>open</function> callback</title>
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static int snd_xxx_open(struct snd_rawmidi_substream *substream);
-]]>
-          </programlisting>
-        </informalexample>
-
-        <para>
-        This is called when a substream is opened.
-        You can initialize the hardware here, but you shouldn't
-        start transmitting/receiving data yet.
-        </para>
-      </section>
-
-      <section id="rawmidi-interface-op-close">
-      <title><function>close</function> callback</title>
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static int snd_xxx_close(struct snd_rawmidi_substream *substream);
-]]>
-          </programlisting>
-        </informalexample>
-
-        <para>
-        Guess what.
-        </para>
-
-        <para>
-        The <function>open</function> and <function>close</function>
-        callbacks of a rawmidi device are serialized with a mutex,
-        and can sleep.
-        </para>
-      </section>
-
-      <section id="rawmidi-interface-op-trigger-out">
-      <title><function>trigger</function> callback for output
-      substreams</title>
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
-]]>
-          </programlisting>
-        </informalexample>
-
-        <para>
-        This is called with a nonzero <parameter>up</parameter>
-        parameter when there is some data in the substream buffer that
-        must be transmitted.
-        </para>
-
-        <para>
-        To read data from the buffer, call
-        <function>snd_rawmidi_transmit_peek</function>.  It will
-        return the number of bytes that have been read; this will be
-        less than the number of bytes requested when there are no more
-        data in the buffer.
-        After the data have been transmitted successfully, call
-        <function>snd_rawmidi_transmit_ack</function> to remove the
-        data from the substream buffer:
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  unsigned char data;
-  while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
-          if (snd_mychip_try_to_transmit(data))
-                  snd_rawmidi_transmit_ack(substream, 1);
-          else
-                  break; /* hardware FIFO full */
-  }
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-        If you know beforehand that the hardware will accept data, you
-        can use the <function>snd_rawmidi_transmit</function> function
-        which reads some data and removes them from the buffer at once:
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  while (snd_mychip_transmit_possible()) {
-          unsigned char data;
-          if (snd_rawmidi_transmit(substream, &data, 1) != 1)
-                  break; /* no more data */
-          snd_mychip_transmit(data);
-  }
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-
-        <para>
-        If you know beforehand how many bytes you can accept, you can
-        use a buffer size greater than one with the
-        <function>snd_rawmidi_transmit*</function> functions.
-        </para>
-
-        <para>
-        The <function>trigger</function> callback must not sleep.  If
-        the hardware FIFO is full before the substream buffer has been
-        emptied, you have to continue transmitting data later, either
-        in an interrupt handler, or with a timer if the hardware
-        doesn't have a MIDI transmit interrupt.
-        </para>
-
-        <para>
-        The <function>trigger</function> callback is called with a
-        zero <parameter>up</parameter> parameter when the transmission
-        of data should be aborted.
-        </para>
-      </section>
-
-      <section id="rawmidi-interface-op-trigger-in">
-      <title><function>trigger</function> callback for input
-      substreams</title>
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
-]]>
-          </programlisting>
-        </informalexample>
-
-        <para>
-        This is called with a nonzero <parameter>up</parameter>
-        parameter to enable receiving data, or with a zero
-        <parameter>up</parameter> parameter do disable receiving data.
-        </para>
-
-        <para>
-        The <function>trigger</function> callback must not sleep; the
-        actual reading of data from the device is usually done in an
-        interrupt handler.
-        </para>
-
-        <para>
-        When data reception is enabled, your interrupt handler should
-        call <function>snd_rawmidi_receive</function> for all received
-        data:
-          <informalexample>
-            <programlisting>
-<![CDATA[
-  void snd_mychip_midi_interrupt(...)
-  {
-          while (mychip_midi_available()) {
-                  unsigned char data;
-                  data = mychip_midi_read();
-                  snd_rawmidi_receive(substream, &data, 1);
-          }
-  }
-]]>
-            </programlisting>
-          </informalexample>
-        </para>
-      </section>
-
-      <section id="rawmidi-interface-op-drain">
-      <title><function>drain</function> callback</title>
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
-]]>
-          </programlisting>
-        </informalexample>
-
-        <para>
-        This is only used with output substreams.  This function should wait
-        until all data read from the substream buffer have been transmitted.
-        This ensures that the device can be closed and the driver unloaded
-        without losing data.
-        </para>
-
-        <para>
-        This callback is optional. If you do not set
-        <structfield>drain</structfield> in the struct snd_rawmidi_ops
-        structure, ALSA will simply wait for 50&nbsp;milliseconds
-        instead.
-        </para>
-      </section>
-    </section>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Miscellaneous Devices  -->
-<!-- ****************************************************** -->
-  <chapter id="misc-devices">
-    <title>Miscellaneous Devices</title>
-
-    <section id="misc-devices-opl3">
-      <title>FM OPL3</title>
-      <para>
-        The FM OPL3 is still used in many chips (mainly for backward
-      compatibility). ALSA has a nice OPL3 FM control layer, too. The
-      OPL3 API is defined in
-      <filename>&lt;sound/opl3.h&gt;</filename>. 
-      </para>
-
-      <para>
-        FM registers can be directly accessed through the direct-FM API,
-      defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
-      ALSA native mode, FM registers are accessed through
-      the Hardware-Dependent Device direct-FM extension API, whereas in
-      OSS compatible mode, FM registers can be accessed with the OSS
-      direct-FM compatible API in <filename>/dev/dmfmX</filename> device. 
-      </para>
-
-      <para>
-        To create the OPL3 component, you have two functions to
-        call. The first one is a constructor for the <type>opl3_t</type>
-        instance. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_opl3 *opl3;
-  snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
-                  integrated, &opl3);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The first argument is the card pointer, the second one is the
-      left port address, and the third is the right port address. In
-      most cases, the right port is placed at the left port + 2. 
-      </para>
-
-      <para>
-        The fourth argument is the hardware type.
-      </para>
-
-      <para>
-        When the left and right ports have been already allocated by
-      the card driver, pass non-zero to the fifth argument
-      (<parameter>integrated</parameter>). Otherwise, the opl3 module will
-      allocate the specified ports by itself. 
-      </para>
-
-      <para>
-        When the accessing the hardware requires special method
-        instead of the standard I/O access, you can create opl3 instance
-        separately with <function>snd_opl3_new()</function>.
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_opl3 *opl3;
-  snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-	Then set <structfield>command</structfield>,
-	<structfield>private_data</structfield> and
-	<structfield>private_free</structfield> for the private
-	access function, the private data and the destructor.
-	The l_port and r_port are not necessarily set.  Only the
-	command must be set properly.  You can retrieve the data
-	from the opl3-&gt;private_data field.
-      </para>
-
-      <para>
-	After creating the opl3 instance via <function>snd_opl3_new()</function>,
-	call <function>snd_opl3_init()</function> to initialize the chip to the
-	proper state. Note that <function>snd_opl3_create()</function> always
-	calls it internally.
-      </para>
-
-      <para>
-        If the opl3 instance is created successfully, then create a
-        hwdep device for this opl3. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_hwdep *opl3hwdep;
-  snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The first argument is the <type>opl3_t</type> instance you
-      created, and the second is the index number, usually 0. 
-      </para>
-
-      <para>
-        The third argument is the index-offset for the sequencer
-      client assigned to the OPL3 port. When there is an MPU401-UART,
-      give 1 for here (UART always takes 0). 
-      </para>
-    </section>
-
-    <section id="misc-devices-hardware-dependent">
-      <title>Hardware-Dependent Devices</title>
-      <para>
-        Some chips need user-space access for special
-      controls or for loading the micro code. In such a case, you can
-      create a hwdep (hardware-dependent) device. The hwdep API is
-      defined in <filename>&lt;sound/hwdep.h&gt;</filename>. You can
-      find examples in opl3 driver or
-      <filename>isa/sb/sb16_csp.c</filename>. 
-      </para>
-
-      <para>
-        The creation of the <type>hwdep</type> instance is done via
-        <function>snd_hwdep_new()</function>. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_hwdep *hw;
-  snd_hwdep_new(card, "My HWDEP", 0, &hw);
-]]>
-          </programlisting>
-        </informalexample>
-
-        where the third argument is the index number.
-      </para>
-
-      <para>
-        You can then pass any pointer value to the
-        <parameter>private_data</parameter>.
-        If you assign a private data, you should define the
-        destructor, too. The destructor function is set in
-        the <structfield>private_free</structfield> field.  
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
-  hw->private_data = p;
-  hw->private_free = mydata_free;
-]]>
-          </programlisting>
-        </informalexample>
-
-        and the implementation of the destructor would be:
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static void mydata_free(struct snd_hwdep *hw)
-  {
-          struct mydata *p = hw->private_data;
-          kfree(p);
-  }
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The arbitrary file operations can be defined for this
-        instance. The file operators are defined in
-        the <parameter>ops</parameter> table. For example, assume that
-        this chip needs an ioctl. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  hw->ops.open = mydata_open;
-  hw->ops.ioctl = mydata_ioctl;
-  hw->ops.release = mydata_release;
-]]>
-          </programlisting>
-        </informalexample>
-
-        And implement the callback functions as you like.
-      </para>
-    </section>
-
-    <section id="misc-devices-IEC958">
-      <title>IEC958 (S/PDIF)</title>
-      <para>
-        Usually the controls for IEC958 devices are implemented via
-      the control interface. There is a macro to compose a name string for
-      IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
-      defined in <filename>&lt;include/asound.h&gt;</filename>.  
-      </para>
-
-      <para>
-        There are some standard controls for IEC958 status bits. These
-      controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
-      and the size of element is fixed as 4 bytes array
-      (value.iec958.status[x]). For the <structfield>info</structfield>
-      callback, you don't specify 
-      the value field for this type (the count field must be set,
-      though). 
-      </para>
-
-      <para>
-        <quote>IEC958 Playback Con Mask</quote> is used to return the
-      bit-mask for the IEC958 status bits of consumer mode. Similarly,
-      <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
-      professional mode. They are read-only controls, and are defined
-      as MIXER controls (iface =
-      <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).  
-      </para>
-
-      <para>
-        Meanwhile, <quote>IEC958 Playback Default</quote> control is
-      defined for getting and setting the current default IEC958
-      bits. Note that this one is usually defined as a PCM control
-      (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
-      although in some places it's defined as a MIXER control. 
-      </para>
-
-      <para>
-        In addition, you can define the control switches to
-      enable/disable or to set the raw bit mode. The implementation
-      will depend on the chip, but the control should be named as
-      <quote>IEC958 xxx</quote>, preferably using
-      the <function>SNDRV_CTL_NAME_IEC958()</function> macro. 
-      </para>
-
-      <para>
-        You can find several cases, for example,
-      <filename>pci/emu10k1</filename>,
-      <filename>pci/ice1712</filename>, or
-      <filename>pci/cmipci.c</filename>.  
-      </para>
-    </section>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Buffer and Memory Management  -->
-<!-- ****************************************************** -->
-  <chapter id="buffer-and-memory">
-    <title>Buffer and Memory Management</title>
-
-    <section id="buffer-and-memory-buffer-types">
-      <title>Buffer Types</title>
-      <para>
-        ALSA provides several different buffer allocation functions
-      depending on the bus and the architecture. All these have a
-      consistent API. The allocation of physically-contiguous pages is
-      done via 
-      <function>snd_malloc_xxx_pages()</function> function, where xxx
-      is the bus type. 
-      </para>
-
-      <para>
-        The allocation of pages with fallback is
-      <function>snd_malloc_xxx_pages_fallback()</function>. This
-      function tries to allocate the specified pages but if the pages
-      are not available, it tries to reduce the page sizes until
-      enough space is found.
-      </para>
-
-      <para>
-      The release the pages, call
-      <function>snd_free_xxx_pages()</function> function. 
-      </para>
-
-      <para>
-      Usually, ALSA drivers try to allocate and reserve
-       a large contiguous physical space
-       at the time the module is loaded for the later use.
-       This is called <quote>pre-allocation</quote>.
-       As already written, you can call the following function at 
-       pcm instance construction time (in the case of PCI bus). 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
-                                        snd_dma_pci_data(pci), size, max);
-]]>
-          </programlisting>
-        </informalexample>
-
-        where <parameter>size</parameter> is the byte size to be
-      pre-allocated and the <parameter>max</parameter> is the maximum
-      size to be changed via the <filename>prealloc</filename> proc file.
-      The allocator will try to get an area as large as possible
-      within the given size. 
-      </para>
-
-      <para>
-      The second argument (type) and the third argument (device pointer)
-      are dependent on the bus.
-      In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
-      as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
-      For the continuous buffer unrelated to the bus can be pre-allocated
-      with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
-      <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
-      where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
-      use.
-      For the PCI scatter-gather buffers, use
-      <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
-      <function>snd_dma_pci_data(pci)</function>
-      (see the 
-          <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
-          </citetitle></link> section).
-      </para>
-
-      <para>
-        Once the buffer is pre-allocated, you can use the
-        allocator in the <structfield>hw_params</structfield> callback: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_pcm_lib_malloc_pages(substream, size);
-]]>
-          </programlisting>
-        </informalexample>
-
-        Note that you have to pre-allocate to use this function.
-      </para>
-    </section>
-
-    <section id="buffer-and-memory-external-hardware">
-      <title>External Hardware Buffers</title>
-      <para>
-        Some chips have their own hardware buffers and the DMA
-      transfer from the host memory is not available. In such a case,
-      you need to either 1) copy/set the audio data directly to the
-      external hardware buffer, or 2) make an intermediate buffer and
-      copy/set the data from it to the external hardware buffer in
-      interrupts (or in tasklets, preferably).
-      </para>
-
-      <para>
-        The first case works fine if the external hardware buffer is large
-      enough.  This method doesn't need any extra buffers and thus is
-      more effective. You need to define the
-      <structfield>copy</structfield> and
-      <structfield>silence</structfield> callbacks for 
-      the data transfer. However, there is a drawback: it cannot
-      be mmapped. The examples are GUS's GF1 PCM or emu8000's
-      wavetable PCM. 
-      </para>
-
-      <para>
-        The second case allows for mmap on the buffer, although you have
-      to handle an interrupt or a tasklet to transfer the data
-      from the intermediate buffer to the hardware buffer. You can find an
-      example in the vxpocket driver. 
-      </para>
-
-      <para>
-        Another case is when the chip uses a PCI memory-map
-      region for the buffer instead of the host memory. In this case,
-      mmap is available only on certain architectures like the Intel one.
-      In non-mmap mode, the data cannot be transferred as in the normal
-      way. Thus you need to define the <structfield>copy</structfield> and
-      <structfield>silence</structfield> callbacks as well, 
-      as in the cases above. The examples are found in
-      <filename>rme32.c</filename> and <filename>rme96.c</filename>. 
-      </para>
-
-      <para>
-        The implementation of the <structfield>copy</structfield> and
-        <structfield>silence</structfield> callbacks depends upon 
-        whether the hardware supports interleaved or non-interleaved
-        samples. The <structfield>copy</structfield> callback is
-        defined like below, a bit 
-        differently depending whether the direction is playback or
-        capture: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static int playback_copy(struct snd_pcm_substream *substream, int channel,
-               snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
-  static int capture_copy(struct snd_pcm_substream *substream, int channel,
-               snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        In the case of interleaved samples, the second argument
-      (<parameter>channel</parameter>) is not used. The third argument
-      (<parameter>pos</parameter>) points the 
-      current position offset in frames. 
-      </para>
-
-      <para>
-        The meaning of the fourth argument is different between
-      playback and capture. For playback, it holds the source data
-      pointer, and for capture, it's the destination data pointer. 
-      </para>
-
-      <para>
-        The last argument is the number of frames to be copied.
-      </para>
-
-      <para>
-        What you have to do in this callback is again different
-        between playback and capture directions. In the
-        playback case, you copy the given amount of data
-        (<parameter>count</parameter>) at the specified pointer
-        (<parameter>src</parameter>) to the specified offset
-        (<parameter>pos</parameter>) on the hardware buffer. When
-        coded like memcpy-like way, the copy would be like: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
-            frames_to_bytes(runtime, count));
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        For the capture direction, you copy the given amount of
-        data (<parameter>count</parameter>) at the specified offset
-        (<parameter>pos</parameter>) on the hardware buffer to the
-        specified pointer (<parameter>dst</parameter>). 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
-            frames_to_bytes(runtime, count));
-]]>
-          </programlisting>
-        </informalexample>
-
-        Note that both the position and the amount of data are given
-      in frames. 
-      </para>
-
-      <para>
-        In the case of non-interleaved samples, the implementation
-      will be a bit more complicated. 
-      </para>
-
-      <para>
-        You need to check the channel argument, and if it's -1, copy
-      the whole channels. Otherwise, you have to copy only the
-      specified channel. Please check
-      <filename>isa/gus/gus_pcm.c</filename> as an example. 
-      </para>
-
-      <para>
-        The <structfield>silence</structfield> callback is also
-        implemented in a similar way. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  static int silence(struct snd_pcm_substream *substream, int channel,
-                     snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        The meanings of arguments are the same as in the
-      <structfield>copy</structfield> 
-      callback, although there is no <parameter>src/dst</parameter>
-      argument. In the case of interleaved samples, the channel
-      argument has no meaning, as well as on
-      <structfield>copy</structfield> callback.  
-      </para>
-
-      <para>
-        The role of <structfield>silence</structfield> callback is to
-        set the given amount 
-        (<parameter>count</parameter>) of silence data at the
-        specified offset (<parameter>pos</parameter>) on the hardware
-        buffer. Suppose that the data format is signed (that is, the
-        silent-data is 0), and the implementation using a memset-like
-        function would be like: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
-            frames_to_bytes(runtime, count));
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        In the case of non-interleaved samples, again, the
-      implementation becomes a bit more complicated. See, for example,
-      <filename>isa/gus/gus_pcm.c</filename>. 
-      </para>
-    </section>
-
-    <section id="buffer-and-memory-non-contiguous">
-      <title>Non-Contiguous Buffers</title>
-      <para>
-        If your hardware supports the page table as in emu10k1 or the
-      buffer descriptors as in via82xx, you can use the scatter-gather
-      (SG) DMA. ALSA provides an interface for handling SG-buffers.
-      The API is provided in <filename>&lt;sound/pcm.h&gt;</filename>. 
-      </para>
-
-      <para>
-        For creating the SG-buffer handler, call
-        <function>snd_pcm_lib_preallocate_pages()</function> or
-        <function>snd_pcm_lib_preallocate_pages_for_all()</function>
-        with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
-	in the PCM constructor like other PCI pre-allocator.
-        You need to pass <function>snd_dma_pci_data(pci)</function>,
-        where pci is the struct <structname>pci_dev</structname> pointer
-        of the chip as well.
-        The <type>struct snd_sg_buf</type> instance is created as
-        substream-&gt;dma_private. You can cast
-        the pointer like: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        Then call <function>snd_pcm_lib_malloc_pages()</function>
-      in the <structfield>hw_params</structfield> callback
-      as well as in the case of normal PCI buffer.
-      The SG-buffer handler will allocate the non-contiguous kernel
-      pages of the given size and map them onto the virtually contiguous
-      memory.  The virtual pointer is addressed in runtime-&gt;dma_area.
-      The physical address (runtime-&gt;dma_addr) is set to zero,
-      because the buffer is physically non-contiguous.
-      The physical address table is set up in sgbuf-&gt;table.
-      You can get the physical address at a certain offset via
-      <function>snd_pcm_sgbuf_get_addr()</function>. 
-      </para>
-
-      <para>
-        When a SG-handler is used, you need to set
-      <function>snd_pcm_sgbuf_ops_page</function> as
-      the <structfield>page</structfield> callback.
-      (See <link linkend="pcm-interface-operators-page-callback">
-      <citetitle>page callback section</citetitle></link>.)
-      </para>
-
-      <para>
-        To release the data, call
-      <function>snd_pcm_lib_free_pages()</function> in the
-      <structfield>hw_free</structfield> callback as usual.
-      </para>
-    </section>
-
-    <section id="buffer-and-memory-vmalloced">
-      <title>Vmalloc'ed Buffers</title>
-      <para>
-        It's possible to use a buffer allocated via
-      <function>vmalloc</function>, for example, for an intermediate
-      buffer. Since the allocated pages are not contiguous, you need
-      to set the <structfield>page</structfield> callback to obtain
-      the physical address at every offset. 
-      </para>
-
-      <para>
-        The implementation of <structfield>page</structfield> callback
-        would be like this: 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  #include <linux/vmalloc.h>
-
-  /* get the physical page pointer on the given offset */
-  static struct page *mychip_page(struct snd_pcm_substream *substream,
-                                  unsigned long offset)
-  {
-          void *pageptr = substream->runtime->dma_area + offset;
-          return vmalloc_to_page(pageptr);
-  }
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-    </section>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Proc Interface  -->
-<!-- ****************************************************** -->
-  <chapter id="proc-interface">
-    <title>Proc Interface</title>
-    <para>
-      ALSA provides an easy interface for procfs. The proc files are
-      very useful for debugging. I recommend you set up proc files if
-      you write a driver and want to get a running status or register
-      dumps. The API is found in
-      <filename>&lt;sound/info.h&gt;</filename>. 
-    </para>
-
-    <para>
-      To create a proc file, call
-      <function>snd_card_proc_new()</function>. 
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  struct snd_info_entry *entry;
-  int err = snd_card_proc_new(card, "my-file", &entry);
-]]>
-        </programlisting>
-      </informalexample>
-
-      where the second argument specifies the name of the proc file to be
-    created. The above example will create a file
-    <filename>my-file</filename> under the card directory,
-    e.g. <filename>/proc/asound/card0/my-file</filename>. 
-    </para>
-
-    <para>
-    Like other components, the proc entry created via
-    <function>snd_card_proc_new()</function> will be registered and
-    released automatically in the card registration and release
-    functions.
-    </para>
-
-    <para>
-      When the creation is successful, the function stores a new
-    instance in the pointer given in the third argument.
-    It is initialized as a text proc file for read only.  To use
-    this proc file as a read-only text file as it is, set the read
-    callback with a private data via 
-     <function>snd_info_set_text_ops()</function>.
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  snd_info_set_text_ops(entry, chip, my_proc_read);
-]]>
-        </programlisting>
-      </informalexample>
-    
-    where the second argument (<parameter>chip</parameter>) is the
-    private data to be used in the callbacks. The third parameter
-    specifies the read buffer size and the fourth
-    (<parameter>my_proc_read</parameter>) is the callback function, which
-    is defined like
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  static void my_proc_read(struct snd_info_entry *entry,
-                           struct snd_info_buffer *buffer);
-]]>
-        </programlisting>
-      </informalexample>
-    
-    </para>
-
-    <para>
-    In the read callback, use <function>snd_iprintf()</function> for
-    output strings, which works just like normal
-    <function>printf()</function>.  For example,
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  static void my_proc_read(struct snd_info_entry *entry,
-                           struct snd_info_buffer *buffer)
-  {
-          struct my_chip *chip = entry->private_data;
-
-          snd_iprintf(buffer, "This is my chip!\n");
-          snd_iprintf(buffer, "Port = %ld\n", chip->port);
-  }
-]]>
-        </programlisting>
-      </informalexample>
-    </para>
-
-    <para>
-    The file permissions can be changed afterwards.  As default, it's
-    set as read only for all users.  If you want to add write
-    permission for the user (root as default), do as follows:
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
- entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
-]]>
-        </programlisting>
-      </informalexample>
-
-    and set the write buffer size and the callback
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  entry->c.text.write = my_proc_write;
-]]>
-        </programlisting>
-      </informalexample>
-    </para>
-
-    <para>
-      For the write callback, you can use
-    <function>snd_info_get_line()</function> to get a text line, and
-    <function>snd_info_get_str()</function> to retrieve a string from
-    the line. Some examples are found in
-    <filename>core/oss/mixer_oss.c</filename>, core/oss/and
-    <filename>pcm_oss.c</filename>. 
-    </para>
-
-    <para>
-      For a raw-data proc-file, set the attributes as follows:
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  static struct snd_info_entry_ops my_file_io_ops = {
-          .read = my_file_io_read,
-  };
-
-  entry->content = SNDRV_INFO_CONTENT_DATA;
-  entry->private_data = chip;
-  entry->c.ops = &my_file_io_ops;
-  entry->size = 4096;
-  entry->mode = S_IFREG | S_IRUGO;
-]]>
-        </programlisting>
-      </informalexample>
-
-      For the raw data, <structfield>size</structfield> field must be
-      set properly.  This specifies the maximum size of the proc file access.
-    </para>
-
-    <para>
-      The read/write callbacks of raw mode are more direct than the text mode.
-      You need to use a low-level I/O functions such as
-      <function>copy_from/to_user()</function> to transfer the
-      data.
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  static ssize_t my_file_io_read(struct snd_info_entry *entry,
-                              void *file_private_data,
-                              struct file *file,
-                              char *buf,
-                              size_t count,
-                              loff_t pos)
-  {
-          if (copy_to_user(buf, local_data + pos, count))
-                  return -EFAULT;
-          return count;
-  }
-]]>
-        </programlisting>
-      </informalexample>
-
-      If the size of the info entry has been set up properly,
-      <structfield>count</structfield> and <structfield>pos</structfield> are
-      guaranteed to fit within 0 and the given size.
-      You don't have to check the range in the callbacks unless any
-      other condition is required.
-
-    </para>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Power Management  -->
-<!-- ****************************************************** -->
-  <chapter id="power-management">
-    <title>Power Management</title>
-    <para>
-      If the chip is supposed to work with suspend/resume
-      functions, you need to add power-management code to the
-      driver. The additional code for power-management should be
-      <function>ifdef</function>'ed with
-      <constant>CONFIG_PM</constant>. 
-    </para>
-
-	<para>
-	If the driver <emphasis>fully</emphasis> supports suspend/resume
-	that is, the device can be
-	properly resumed to its state when suspend was called,
-	you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
-	in the pcm info field.  Usually, this is possible when the
-	registers of the chip can be safely saved and restored to
-	RAM. If this is set, the trigger callback is called with
-	<constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
-	callback completes. 
-	</para>
-
-	<para>
-	Even if the driver doesn't support PM fully but 
-	partial suspend/resume is still possible, it's still worthy to
-	implement suspend/resume callbacks. In such a case, applications
-	would reset the status by calling
-	<function>snd_pcm_prepare()</function> and restart the stream
-	appropriately.  Hence, you can define suspend/resume callbacks
-	below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
-	info flag to the PCM.
-	</para>
-	
-	<para>
-	Note that the trigger with SUSPEND can always be called when
-	<function>snd_pcm_suspend_all</function> is called,
-	regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
-	The <constant>RESUME</constant> flag affects only the behavior
-	of <function>snd_pcm_resume()</function>.
-	(Thus, in theory,
-	<constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
-	to be handled in the trigger callback when no
-	<constant>SNDRV_PCM_INFO_RESUME</constant> flag is set.  But,
-	it's better to keep it for compatibility reasons.)
-	</para>
-    <para>
-      In the earlier version of ALSA drivers, a common
-      power-management layer was provided, but it has been removed.
-      The driver needs to define the suspend/resume hooks according to
-      the bus the device is connected to.  In the case of PCI drivers, the
-      callbacks look like below:
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  #ifdef CONFIG_PM
-  static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
-  {
-          .... /* do things for suspend */
-          return 0;
-  }
-  static int snd_my_resume(struct pci_dev *pci)
-  {
-          .... /* do things for suspend */
-          return 0;
-  }
-  #endif
-]]>
-        </programlisting>
-      </informalexample>
-    </para>
-
-    <para>
-      The scheme of the real suspend job is as follows.
-
-      <orderedlist>
-        <listitem><para>Retrieve the card and the chip data.</para></listitem>
-        <listitem><para>Call <function>snd_power_change_state()</function> with
-	  <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
-	  power status.</para></listitem>
-        <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
-	<listitem><para>If AC97 codecs are used, call
-	<function>snd_ac97_suspend()</function> for each codec.</para></listitem>
-        <listitem><para>Save the register values if necessary.</para></listitem>
-        <listitem><para>Stop the hardware if necessary.</para></listitem>
-        <listitem><para>Disable the PCI device by calling
-	  <function>pci_disable_device()</function>.  Then, call
-          <function>pci_save_state()</function> at last.</para></listitem>
-      </orderedlist>
-    </para>
-
-    <para>
-      A typical code would be like:
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
-  {
-          /* (1) */
-          struct snd_card *card = pci_get_drvdata(pci);
-          struct mychip *chip = card->private_data;
-          /* (2) */
-          snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
-          /* (3) */
-          snd_pcm_suspend_all(chip->pcm);
-          /* (4) */
-          snd_ac97_suspend(chip->ac97);
-          /* (5) */
-          snd_mychip_save_registers(chip);
-          /* (6) */
-          snd_mychip_stop_hardware(chip);
-          /* (7) */
-          pci_disable_device(pci);
-          pci_save_state(pci);
-          return 0;
-  }
-]]>
-        </programlisting>
-      </informalexample>
-    </para>
-
-    <para>
-    The scheme of the real resume job is as follows.
-
-    <orderedlist>
-    <listitem><para>Retrieve the card and the chip data.</para></listitem>
-    <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
-    	Then enable the pci device again by calling <function>pci_enable_device()</function>.
-	Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
-    <listitem><para>Re-initialize the chip.</para></listitem>
-    <listitem><para>Restore the saved registers if necessary.</para></listitem>
-    <listitem><para>Resume the mixer, e.g. calling
-    <function>snd_ac97_resume()</function>.</para></listitem>
-    <listitem><para>Restart the hardware (if any).</para></listitem>
-    <listitem><para>Call <function>snd_power_change_state()</function> with
-	<constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
-    </orderedlist>
-    </para>
-
-    <para>
-    A typical code would be like:
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  static int mychip_resume(struct pci_dev *pci)
-  {
-          /* (1) */
-          struct snd_card *card = pci_get_drvdata(pci);
-          struct mychip *chip = card->private_data;
-          /* (2) */
-          pci_restore_state(pci);
-          pci_enable_device(pci);
-          pci_set_master(pci);
-          /* (3) */
-          snd_mychip_reinit_chip(chip);
-          /* (4) */
-          snd_mychip_restore_registers(chip);
-          /* (5) */
-          snd_ac97_resume(chip->ac97);
-          /* (6) */
-          snd_mychip_restart_chip(chip);
-          /* (7) */
-          snd_power_change_state(card, SNDRV_CTL_POWER_D0);
-          return 0;
-  }
-]]>
-        </programlisting>
-      </informalexample>
-    </para>
-
-    <para>
-	As shown in the above, it's better to save registers after
-	suspending the PCM operations via
-	<function>snd_pcm_suspend_all()</function> or
-	<function>snd_pcm_suspend()</function>.  It means that the PCM
-	streams are already stopped when the register snapshot is
-	taken.  But, remember that you don't have to restart the PCM
-	stream in the resume callback. It'll be restarted via 
-	trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
-	when necessary.
-    </para>
-
-    <para>
-      OK, we have all callbacks now. Let's set them up. In the
-      initialization of the card, make sure that you can get the chip
-      data from the card instance, typically via
-      <structfield>private_data</structfield> field, in case you
-      created the chip data individually.
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  static int snd_mychip_probe(struct pci_dev *pci,
-                              const struct pci_device_id *pci_id)
-  {
-          ....
-          struct snd_card *card;
-          struct mychip *chip;
-          int err;
-          ....
-          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
-                             0, &card);
-          ....
-          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
-          ....
-          card->private_data = chip;
-          ....
-  }
-]]>
-        </programlisting>
-      </informalexample>
-
-	When you created the chip data with
-	<function>snd_card_new()</function>, it's anyway accessible
-	via <structfield>private_data</structfield> field.
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  static int snd_mychip_probe(struct pci_dev *pci,
-                              const struct pci_device_id *pci_id)
-  {
-          ....
-          struct snd_card *card;
-          struct mychip *chip;
-          int err;
-          ....
-          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
-                             sizeof(struct mychip), &card);
-          ....
-          chip = card->private_data;
-          ....
-  }
-]]>
-        </programlisting>
-      </informalexample>
-
-    </para>
-
-    <para>
-      If you need a space to save the registers, allocate the
-	buffer for it here, too, since it would be fatal
-    if you cannot allocate a memory in the suspend phase.
-    The allocated buffer should be released in the corresponding
-    destructor.
-    </para>
-
-    <para>
-      And next, set suspend/resume callbacks to the pci_driver.
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  static struct pci_driver driver = {
-          .name = KBUILD_MODNAME,
-          .id_table = snd_my_ids,
-          .probe = snd_my_probe,
-          .remove = snd_my_remove,
-  #ifdef CONFIG_PM
-          .suspend = snd_my_suspend,
-          .resume = snd_my_resume,
-  #endif
-  };
-]]>
-        </programlisting>
-      </informalexample>
-    </para>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Module Parameters  -->
-<!-- ****************************************************** -->
-  <chapter id="module-parameters">
-    <title>Module Parameters</title>
-    <para>
-      There are standard module options for ALSA. At least, each
-      module should have the <parameter>index</parameter>,
-      <parameter>id</parameter> and <parameter>enable</parameter>
-      options. 
-    </para>
-
-    <para>
-      If the module supports multiple cards (usually up to
-      8 = <constant>SNDRV_CARDS</constant> cards), they should be
-      arrays. The default initial values are defined already as
-      constants for easier programming:
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
-  static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
-  static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
-]]>
-        </programlisting>
-      </informalexample>
-    </para>
-
-    <para>
-      If the module supports only a single card, they could be single
-    variables, instead.  <parameter>enable</parameter> option is not
-    always necessary in this case, but it would be better to have a
-    dummy option for compatibility.
-    </para>
-
-    <para>
-      The module parameters must be declared with the standard
-    <function>module_param()()</function>,
-    <function>module_param_array()()</function> and
-    <function>MODULE_PARM_DESC()</function> macros.
-    </para>
-
-    <para>
-      The typical coding would be like below:
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  #define CARD_NAME "My Chip"
-
-  module_param_array(index, int, NULL, 0444);
-  MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
-  module_param_array(id, charp, NULL, 0444);
-  MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
-  module_param_array(enable, bool, NULL, 0444);
-  MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
-]]>
-        </programlisting>
-      </informalexample>
-    </para>
-
-    <para>
-      Also, don't forget to define the module description, classes,
-      license and devices. Especially, the recent modprobe requires to
-      define the module license as GPL, etc., otherwise the system is
-      shown as <quote>tainted</quote>. 
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  MODULE_DESCRIPTION("My Chip");
-  MODULE_LICENSE("GPL");
-  MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
-]]>
-        </programlisting>
-      </informalexample>
-    </para>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- How To Put Your Driver  -->
-<!-- ****************************************************** -->
-  <chapter id="how-to-put-your-driver">
-    <title>How To Put Your Driver Into ALSA Tree</title>
-	<section>
-	<title>General</title>
-	<para>
-	So far, you've learned how to write the driver codes.
-	And you might have a question now: how to put my own
-	driver into the ALSA driver tree?
-	Here (finally :) the standard procedure is described briefly.
-	</para>
-
-	<para>
-	Suppose that you create a new PCI driver for the card
-	<quote>xyz</quote>.  The card module name would be
-	snd-xyz.  The new driver is usually put into the alsa-driver
-	tree, <filename>alsa-driver/pci</filename> directory in
-	the case of PCI cards.
-	Then the driver is evaluated, audited and tested
-	by developers and users.  After a certain time, the driver
-	will go to the alsa-kernel tree (to the corresponding directory,
-	such as <filename>alsa-kernel/pci</filename>) and eventually
- 	will be integrated into the Linux 2.6 tree (the directory would be
-	<filename>linux/sound/pci</filename>).
-	</para>
-
-	<para>
-	In the following sections, the driver code is supposed
-	to be put into alsa-driver tree. The two cases are covered:
-	a driver consisting of a single source file and one consisting
-	of several source files.
-	</para>
-	</section>
-
-	<section>
-	<title>Driver with A Single Source File</title>
-	<para>
-	<orderedlist>
-	<listitem>
-	<para>
-	Modify alsa-driver/pci/Makefile
-	</para>
-
-	<para>
-	Suppose you have a file xyz.c.  Add the following
-	two lines
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  snd-xyz-objs := xyz.o
-  obj-$(CONFIG_SND_XYZ) += snd-xyz.o
-]]>
-        </programlisting>
-      </informalexample>
-	</para>
-	</listitem>
-
-	<listitem>
-	<para>
-	Create the Kconfig entry
-	</para>
-
-	<para>
-	Add the new entry of Kconfig for your xyz driver.
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  config SND_XYZ
-          tristate "Foobar XYZ"
-          depends on SND
-          select SND_PCM
-          help
-            Say Y here to include support for Foobar XYZ soundcard.
-
-            To compile this driver as a module, choose M here: the module
-            will be called snd-xyz.
-]]>
-        </programlisting>
-      </informalexample>
-
-	the line, select SND_PCM, specifies that the driver xyz supports
-	PCM.  In addition to SND_PCM, the following components are
-	supported for select command:
-	SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
-	SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
-	Add the select command for each supported component.
-	</para>
-
-	<para>
-	Note that some selections imply the lowlevel selections.
-	For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
-	AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
-	You don't need to give the lowlevel selections again.
-	</para>
-
-	<para>
-	For the details of Kconfig script, refer to the kbuild
-	documentation.
-	</para>
-
-	</listitem>
-
-	<listitem>
-	<para>
-	Run cvscompile script to re-generate the configure script and
-	build the whole stuff again.
-	</para>
-	</listitem>
-	</orderedlist>
-	</para>
-	</section>
-
-	<section>
-	<title>Drivers with Several Source Files</title>
-	<para>
-	Suppose that the driver snd-xyz have several source files.
-	They are located in the new subdirectory,
-	pci/xyz.
-
-	<orderedlist>
-	<listitem>
-	<para>
-	Add a new directory (<filename>xyz</filename>) in
-	<filename>alsa-driver/pci/Makefile</filename> as below
-
-      <informalexample>
-        <programlisting>
-<![CDATA[
-  obj-$(CONFIG_SND) += xyz/
-]]>
-        </programlisting>
-      </informalexample>
-	</para>
-	</listitem>
-
-	<listitem>
-	<para>
-	Under the directory <filename>xyz</filename>, create a Makefile
-
-      <example>
-	<title>Sample Makefile for a driver xyz</title>
-        <programlisting>
-<![CDATA[
-  ifndef SND_TOPDIR
-  SND_TOPDIR=../..
-  endif
-
-  include $(SND_TOPDIR)/toplevel.config
-  include $(SND_TOPDIR)/Makefile.conf
-
-  snd-xyz-objs := xyz.o abc.o def.o
-
-  obj-$(CONFIG_SND_XYZ) += snd-xyz.o
-
-  include $(SND_TOPDIR)/Rules.make
-]]>
-        </programlisting>
-      </example>
-	</para>
-	</listitem>
-
-	<listitem>
-	<para>
-	Create the Kconfig entry
-	</para>
-
-	<para>
-	This procedure is as same as in the last section.
-	</para>
-	</listitem>
-
-	<listitem>
-	<para>
-	Run cvscompile script to re-generate the configure script and
-	build the whole stuff again.
-	</para>
-	</listitem>
-	</orderedlist>
-	</para>
-	</section>
-
-  </chapter>
-
-<!-- ****************************************************** -->
-<!-- Useful Functions  -->
-<!-- ****************************************************** -->
-  <chapter id="useful-functions">
-    <title>Useful Functions</title>
-
-    <section id="useful-functions-snd-printk">
-      <title><function>snd_printk()</function> and friends</title>
-      <para>
-        ALSA provides a verbose version of the
-      <function>printk()</function> function. If a kernel config
-      <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
-      function prints the given message together with the file name
-      and the line of the caller. The <constant>KERN_XXX</constant>
-      prefix is processed as 
-      well as the original <function>printk()</function> does, so it's
-      recommended to add this prefix, e.g. 
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
-]]>
-          </programlisting>
-        </informalexample>
-      </para>
-
-      <para>
-        There are also <function>printk()</function>'s for
-      debugging. <function>snd_printd()</function> can be used for
-      general debugging purposes. If
-      <constant>CONFIG_SND_DEBUG</constant> is set, this function is
-      compiled, and works just like
-      <function>snd_printk()</function>. If the ALSA is compiled
-      without the debugging flag, it's ignored. 
-      </para>
-
-      <para>
-        <function>snd_printdd()</function> is compiled in only when
-      <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
-      that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
-      even if you configure the alsa-driver with
-      <option>--with-debug=full</option> option. You need to give
-      explicitly <option>--with-debug=detect</option> option instead. 
-      </para>
-    </section>
-
-    <section id="useful-functions-snd-bug">
-      <title><function>snd_BUG()</function></title>
-      <para>
-        It shows the <computeroutput>BUG?</computeroutput> message and
-      stack trace as well as <function>snd_BUG_ON</function> at the point.
-      It's useful to show that a fatal error happens there. 
-      </para>
-      <para>
-	 When no debug flag is set, this macro is ignored. 
-      </para>
-    </section>
-
-    <section id="useful-functions-snd-bug-on">
-      <title><function>snd_BUG_ON()</function></title>
-      <para>
-        <function>snd_BUG_ON()</function> macro is similar with
-	<function>WARN_ON()</function> macro. For example,  
-
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  snd_BUG_ON(!pointer);
-]]>
-          </programlisting>
-        </informalexample>
-
-	or it can be used as the condition,
-        <informalexample>
-          <programlisting>
-<![CDATA[
-  if (snd_BUG_ON(non_zero_is_bug))
-          return -EINVAL;
-]]>
-          </programlisting>
-        </informalexample>
-
-      </para>
-
-      <para>
-        The macro takes an conditional expression to evaluate.
-	When <constant>CONFIG_SND_DEBUG</constant>, is set, if the
-	expression is non-zero, it shows the warning message such as
-	<computeroutput>BUG? (xxx)</computeroutput>
-	normally followed by stack trace.
-
-	In both cases it returns the evaluated value.
-      </para>
-
-    </section>
-
-  </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Acknowledgments  -->
-<!-- ****************************************************** -->
-  <chapter id="acknowledgments">
-    <title>Acknowledgments</title>
-    <para>
-      I would like to thank Phil Kerr for his help for improvement and
-      corrections of this document. 
-    </para>
-    <para>
-    Kevin Conder reformatted the original plain-text to the
-    DocBook format.
-    </para>
-    <para>
-    Giuliano Pochini corrected typos and contributed the example codes
-    in the hardware constraints section.
-    </para>
-  </chapter>
-</book>
diff --git a/Documentation/HOWTO b/Documentation/HOWTO
deleted file mode 100644
index 5f04234..0000000
--- a/Documentation/HOWTO
+++ /dev/null
@@ -1,652 +0,0 @@
-HOWTO do Linux kernel development
-=================================
-
-This is the be-all, end-all document on this topic.  It contains
-instructions on how to become a Linux kernel developer and how to learn
-to work with the Linux kernel development community.  It tries to not
-contain anything related to the technical aspects of kernel programming,
-but will help point you in the right direction for that.
-
-If anything in this document becomes out of date, please send in patches
-to the maintainer of this file, who is listed at the bottom of the
-document.
-
-
-Introduction
-------------
-
-So, you want to learn how to become a Linux kernel developer?  Or you
-have been told by your manager, "Go write a Linux driver for this
-device."  This document's goal is to teach you everything you need to
-know to achieve this by describing the process you need to go through,
-and hints on how to work with the community.  It will also try to
-explain some of the reasons why the community works like it does.
-
-The kernel is written mostly in C, with some architecture-dependent
-parts written in assembly. A good understanding of C is required for
-kernel development.  Assembly (any architecture) is not required unless
-you plan to do low-level development for that architecture.  Though they
-are not a good substitute for a solid C education and/or years of
-experience, the following books are good for, if anything, reference:
-
- - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
- - "Practical C Programming" by Steve Oualline [O'Reilly]
- - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
-
-The kernel is written using GNU C and the GNU toolchain.  While it
-adheres to the ISO C89 standard, it uses a number of extensions that are
-not featured in the standard.  The kernel is a freestanding C
-environment, with no reliance on the standard C library, so some
-portions of the C standard are not supported.  Arbitrary long long
-divisions and floating point are not allowed.  It can sometimes be
-difficult to understand the assumptions the kernel has on the toolchain
-and the extensions that it uses, and unfortunately there is no
-definitive reference for them.  Please check the gcc info pages (`info
-gcc`) for some information on them.
-
-Please remember that you are trying to learn how to work with the
-existing development community.  It is a diverse group of people, with
-high standards for coding, style and procedure.  These standards have
-been created over time based on what they have found to work best for
-such a large and geographically dispersed team.  Try to learn as much as
-possible about these standards ahead of time, as they are well
-documented; do not expect people to adapt to you or your company's way
-of doing things.
-
-
-Legal Issues
-------------
-
-The Linux kernel source code is released under the GPL.  Please see the
-file, COPYING, in the main directory of the source tree, for details on
-the license.  If you have further questions about the license, please
-contact a lawyer, and do not ask on the Linux kernel mailing list.  The
-people on the mailing lists are not lawyers, and you should not rely on
-their statements on legal matters.
-
-For common questions and answers about the GPL, please see:
-
-	https://www.gnu.org/licenses/gpl-faq.html
-
-
-Documentation
--------------
-
-The Linux kernel source tree has a large range of documents that are
-invaluable for learning how to interact with the kernel community.  When
-new features are added to the kernel, it is recommended that new
-documentation files are also added which explain how to use the feature.
-When a kernel change causes the interface that the kernel exposes to
-userspace to change, it is recommended that you send the information or
-a patch to the manual pages explaining the change to the manual pages
-maintainer at mtk.manpages@gmail.com, and CC the list
-linux-api@vger.kernel.org.
-
-Here is a list of files that are in the kernel source tree that are
-required reading:
-
-  README
-    This file gives a short background on the Linux kernel and describes
-    what is necessary to do to configure and build the kernel.  People
-    who are new to the kernel should start here.
-
-  :ref:`Documentation/Changes <changes>`
-    This file gives a list of the minimum levels of various software
-    packages that are necessary to build and run the kernel
-    successfully.
-
-  :ref:`Documentation/CodingStyle <codingstyle>`
-    This describes the Linux kernel coding style, and some of the
-    rationale behind it. All new code is expected to follow the
-    guidelines in this document. Most maintainers will only accept
-    patches if these rules are followed, and many people will only
-    review code if it is in the proper style.
-
-  :ref:`Documentation/SubmittingPatches <submittingpatches>` and :ref:`Documentation/SubmittingDrivers <submittingdrivers>`
-    These files describe in explicit detail how to successfully create
-    and send a patch, including (but not limited to):
-
-       - Email contents
-       - Email format
-       - Who to send it to
-
-    Following these rules will not guarantee success (as all patches are
-    subject to scrutiny for content and style), but not following them
-    will almost always prevent it.
-
-    Other excellent descriptions of how to create patches properly are:
-
-	"The Perfect Patch"
-		https://www.ozlabs.org/~akpm/stuff/tpp.txt
-
-	"Linux kernel patch submission format"
-		http://linux.yyz.us/patch-format.html
-
-  :ref:`Documentation/stable_api_nonsense.txt <stable_api_nonsense>`
-    This file describes the rationale behind the conscious decision to
-    not have a stable API within the kernel, including things like:
-
-      - Subsystem shim-layers (for compatibility?)
-      - Driver portability between Operating Systems.
-      - Mitigating rapid change within the kernel source tree (or
-	preventing rapid change)
-
-    This document is crucial for understanding the Linux development
-    philosophy and is very important for people moving to Linux from
-    development on other Operating Systems.
-
-  :ref:`Documentation/SecurityBugs <securitybugs>`
-    If you feel you have found a security problem in the Linux kernel,
-    please follow the steps in this document to help notify the kernel
-    developers, and help solve the issue.
-
-  :ref:`Documentation/ManagementStyle <managementstyle>`
-    This document describes how Linux kernel maintainers operate and the
-    shared ethos behind their methodologies.  This is important reading
-    for anyone new to kernel development (or anyone simply curious about
-    it), as it resolves a lot of common misconceptions and confusion
-    about the unique behavior of kernel maintainers.
-
-  :ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
-    This file describes the rules on how the stable kernel releases
-    happen, and what to do if you want to get a change into one of these
-    releases.
-
-  :ref:`Documentation/kernel-docs.txt <kernel_docs>`
-    A list of external documentation that pertains to kernel
-    development.  Please consult this list if you do not find what you
-    are looking for within the in-kernel documentation.
-
-  :ref:`Documentation/applying-patches.txt <applying_patches>`
-    A good introduction describing exactly what a patch is and how to
-    apply it to the different development branches of the kernel.
-
-The kernel also has a large number of documents that can be
-automatically generated from the source code itself or from
-ReStructuredText markups (ReST), like this one. This includes a
-full description of the in-kernel API, and rules on how to handle
-locking properly.
-
-All such documents can be generated as PDF or HTML by running::
-
-	make pdfdocs
-	make htmldocs
-
-respectively from the main kernel source directory.
-
-The documents that uses ReST markup will be generated at Documentation/output.
-They can also be generated on LaTeX and ePub formats with::
-
-	make latexdocs
-	make epubdocs
-
-Currently, there are some documents written on DocBook that are in
-the process of conversion to ReST. Such documents will be created in the
-Documentation/DocBook/ directory and can be generated also as
-Postscript or man pages by running::
-
-	make psdocs
-	make mandocs
-
-Becoming A Kernel Developer
----------------------------
-
-If you do not know anything about Linux kernel development, you should
-look at the Linux KernelNewbies project:
-
-	https://kernelnewbies.org
-
-It consists of a helpful mailing list where you can ask almost any type
-of basic kernel development question (make sure to search the archives
-first, before asking something that has already been answered in the
-past.)  It also has an IRC channel that you can use to ask questions in
-real-time, and a lot of helpful documentation that is useful for
-learning about Linux kernel development.
-
-The website has basic information about code organization, subsystems,
-and current projects (both in-tree and out-of-tree). It also describes
-some basic logistical information, like how to compile a kernel and
-apply a patch.
-
-If you do not know where you want to start, but you want to look for
-some task to start doing to join into the kernel development community,
-go to the Linux Kernel Janitor's project:
-
-	https://kernelnewbies.org/KernelJanitors
-
-It is a great place to start.  It describes a list of relatively simple
-problems that need to be cleaned up and fixed within the Linux kernel
-source tree.  Working with the developers in charge of this project, you
-will learn the basics of getting your patch into the Linux kernel tree,
-and possibly be pointed in the direction of what to go work on next, if
-you do not already have an idea.
-
-If you already have a chunk of code that you want to put into the kernel
-tree, but need some help getting it in the proper form, the
-kernel-mentors project was created to help you out with this.  It is a
-mailing list, and can be found at:
-
-	https://selenic.com/mailman/listinfo/kernel-mentors
-
-Before making any actual modifications to the Linux kernel code, it is
-imperative to understand how the code in question works.  For this
-purpose, nothing is better than reading through it directly (most tricky
-bits are commented well), perhaps even with the help of specialized
-tools.  One such tool that is particularly recommended is the Linux
-Cross-Reference project, which is able to present source code in a
-self-referential, indexed webpage format. An excellent up-to-date
-repository of the kernel code may be found at:
-
-	http://lxr.free-electrons.com/
-
-
-The development process
------------------------
-
-Linux kernel development process currently consists of a few different
-main kernel "branches" and lots of different subsystem-specific kernel
-branches.  These different branches are:
-
-  - main 4.x kernel tree
-  - 4.x.y -stable kernel tree
-  - 4.x -git kernel patches
-  - subsystem specific kernel trees and patches
-  - the 4.x -next kernel tree for integration tests
-
-4.x kernel tree
------------------
-4.x kernels are maintained by Linus Torvalds, and can be found on
-https://kernel.org in the pub/linux/kernel/v4.x/ directory.  Its development
-process is as follows:
-
-  - As soon as a new kernel is released a two weeks window is open,
-    during this period of time maintainers can submit big diffs to
-    Linus, usually the patches that have already been included in the
-    -next kernel for a few weeks.  The preferred way to submit big changes
-    is using git (the kernel's source management tool, more information
-    can be found at https://git-scm.com/) but plain patches are also just
-    fine.
-  - After two weeks a -rc1 kernel is released it is now possible to push
-    only patches that do not include new features that could affect the
-    stability of the whole kernel.  Please note that a whole new driver
-    (or filesystem) might be accepted after -rc1 because there is no
-    risk of causing regressions with such a change as long as the change
-    is self-contained and does not affect areas outside of the code that
-    is being added.  git can be used to send patches to Linus after -rc1
-    is released, but the patches need to also be sent to a public
-    mailing list for review.
-  - A new -rc is released whenever Linus deems the current git tree to
-    be in a reasonably sane state adequate for testing.  The goal is to
-    release a new -rc kernel every week.
-  - Process continues until the kernel is considered "ready", the
-    process should last around 6 weeks.
-
-It is worth mentioning what Andrew Morton wrote on the linux-kernel
-mailing list about kernel releases:
-
-	*"Nobody knows when a kernel will be released, because it's
-	released according to perceived bug status, not according to a
-	preconceived timeline."*
-
-4.x.y -stable kernel tree
--------------------------
-Kernels with 3-part versions are -stable kernels. They contain
-relatively small and critical fixes for security problems or significant
-regressions discovered in a given 4.x kernel.
-
-This is the recommended branch for users who want the most recent stable
-kernel and are not interested in helping test development/experimental
-versions.
-
-If no 4.x.y kernel is available, then the highest numbered 4.x
-kernel is the current stable kernel.
-
-4.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and
-are released as needs dictate.  The normal release period is approximately
-two weeks, but it can be longer if there are no pressing problems.  A
-security-related problem, instead, can cause a release to happen almost
-instantly.
-
-The file Documentation/stable_kernel_rules.txt in the kernel tree
-documents what kinds of changes are acceptable for the -stable tree, and
-how the release process works.
-
-4.x -git patches
-----------------
-These are daily snapshots of Linus' kernel tree which are managed in a
-git repository (hence the name.) These patches are usually released
-daily and represent the current state of Linus' tree.  They are more
-experimental than -rc kernels since they are generated automatically
-without even a cursory glance to see if they are sane.
-
-Subsystem Specific kernel trees and patches
--------------------------------------------
-The maintainers of the various kernel subsystems --- and also many
-kernel subsystem developers --- expose their current state of
-development in source repositories.  That way, others can see what is
-happening in the different areas of the kernel.  In areas where
-development is rapid, a developer may be asked to base his submissions
-onto such a subsystem kernel tree so that conflicts between the
-submission and other already ongoing work are avoided.
-
-Most of these repositories are git trees, but there are also other SCMs
-in use, or patch queues being published as quilt series.  Addresses of
-these subsystem repositories are listed in the MAINTAINERS file.  Many
-of them can be browsed at https://git.kernel.org/.
-
-Before a proposed patch is committed to such a subsystem tree, it is
-subject to review which primarily happens on mailing lists (see the
-respective section below).  For several kernel subsystems, this review
-process is tracked with the tool patchwork.  Patchwork offers a web
-interface which shows patch postings, any comments on a patch or
-revisions to it, and maintainers can mark patches as under review,
-accepted, or rejected.  Most of these patchwork sites are listed at
-https://patchwork.kernel.org/.
-
-4.x -next kernel tree for integration tests
--------------------------------------------
-Before updates from subsystem trees are merged into the mainline 4.x
-tree, they need to be integration-tested.  For this purpose, a special
-testing repository exists into which virtually all subsystem trees are
-pulled on an almost daily basis:
-
-	https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
-
-This way, the -next kernel gives a summary outlook onto what will be
-expected to go into the mainline kernel at the next merge period.
-Adventurous testers are very welcome to runtime-test the -next kernel.
-
-
-Bug Reporting
--------------
-
-https://bugzilla.kernel.org is where the Linux kernel developers track kernel
-bugs.  Users are encouraged to report all bugs that they find in this
-tool.  For details on how to use the kernel bugzilla, please see:
-
-	https://bugzilla.kernel.org/page.cgi?id=faq.html
-
-The file REPORTING-BUGS in the main kernel source directory has a good
-template for how to report a possible kernel bug, and details what kind
-of information is needed by the kernel developers to help track down the
-problem.
-
-
-Managing bug reports
---------------------
-
-One of the best ways to put into practice your hacking skills is by fixing
-bugs reported by other people. Not only you will help to make the kernel
-more stable, you'll learn to fix real world problems and you will improve
-your skills, and other developers will be aware of your presence. Fixing
-bugs is one of the best ways to get merits among other developers, because
-not many people like wasting time fixing other people's bugs.
-
-To work in the already reported bug reports, go to https://bugzilla.kernel.org.
-If you want to be advised of the future bug reports, you can subscribe to the
-bugme-new mailing list (only new bug reports are mailed here) or to the
-bugme-janitor mailing list (every change in the bugzilla is mailed here)
-
-	https://lists.linux-foundation.org/mailman/listinfo/bugme-new
-
-	https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
-
-
-
-Mailing lists
--------------
-
-As some of the above documents describe, the majority of the core kernel
-developers participate on the Linux Kernel Mailing list.  Details on how
-to subscribe and unsubscribe from the list can be found at:
-
-	http://vger.kernel.org/vger-lists.html#linux-kernel
-
-There are archives of the mailing list on the web in many different
-places.  Use a search engine to find these archives.  For example:
-
-	http://dir.gmane.org/gmane.linux.kernel
-
-It is highly recommended that you search the archives about the topic
-you want to bring up, before you post it to the list. A lot of things
-already discussed in detail are only recorded at the mailing list
-archives.
-
-Most of the individual kernel subsystems also have their own separate
-mailing list where they do their development efforts.  See the
-MAINTAINERS file for a list of what these lists are for the different
-groups.
-
-Many of the lists are hosted on kernel.org. Information on them can be
-found at:
-
-	http://vger.kernel.org/vger-lists.html
-
-Please remember to follow good behavioral habits when using the lists.
-Though a bit cheesy, the following URL has some simple guidelines for
-interacting with the list (or any list):
-
-	http://www.albion.com/netiquette/
-
-If multiple people respond to your mail, the CC: list of recipients may
-get pretty large. Don't remove anybody from the CC: list without a good
-reason, or don't reply only to the list address. Get used to receiving the
-mail twice, one from the sender and the one from the list, and don't try
-to tune that by adding fancy mail-headers, people will not like it.
-
-Remember to keep the context and the attribution of your replies intact,
-keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and
-add your statements between the individual quoted sections instead of
-writing at the top of the mail.
-
-If you add patches to your mail, make sure they are plain readable text
-as stated in Documentation/SubmittingPatches.
-Kernel developers don't want to deal with
-attachments or compressed patches; they may want to comment on
-individual lines of your patch, which works only that way. Make sure you
-use a mail program that does not mangle spaces and tab characters. A
-good first test is to send the mail to yourself and try to apply your
-own patch by yourself. If that doesn't work, get your mail program fixed
-or change it until it works.
-
-Above all, please remember to show respect to other subscribers.
-
-
-Working with the community
---------------------------
-
-The goal of the kernel community is to provide the best possible kernel
-there is.  When you submit a patch for acceptance, it will be reviewed
-on its technical merits and those alone.  So, what should you be
-expecting?
-
-  - criticism
-  - comments
-  - requests for change
-  - requests for justification
-  - silence
-
-Remember, this is part of getting your patch into the kernel.  You have
-to be able to take criticism and comments about your patches, evaluate
-them at a technical level and either rework your patches or provide
-clear and concise reasoning as to why those changes should not be made.
-If there are no responses to your posting, wait a few days and try
-again, sometimes things get lost in the huge volume.
-
-What should you not do?
-
-  - expect your patch to be accepted without question
-  - become defensive
-  - ignore comments
-  - resubmit the patch without making any of the requested changes
-
-In a community that is looking for the best technical solution possible,
-there will always be differing opinions on how beneficial a patch is.
-You have to be cooperative, and willing to adapt your idea to fit within
-the kernel.  Or at least be willing to prove your idea is worth it.
-Remember, being wrong is acceptable as long as you are willing to work
-toward a solution that is right.
-
-It is normal that the answers to your first patch might simply be a list
-of a dozen things you should correct.  This does **not** imply that your
-patch will not be accepted, and it is **not** meant against you
-personally.  Simply correct all issues raised against your patch and
-resend it.
-
-
-Differences between the kernel community and corporate structures
------------------------------------------------------------------
-
-The kernel community works differently than most traditional corporate
-development environments.  Here are a list of things that you can try to
-do to avoid problems:
-
-  Good things to say regarding your proposed changes:
-
-    - "This solves multiple problems."
-    - "This deletes 2000 lines of code."
-    - "Here is a patch that explains what I am trying to describe."
-    - "I tested it on 5 different architectures..."
-    - "Here is a series of small patches that..."
-    - "This increases performance on typical machines..."
-
-  Bad things you should avoid saying:
-
-    - "We did it this way in AIX/ptx/Solaris, so therefore it must be
-      good..."
-    - "I've being doing this for 20 years, so..."
-    - "This is required for my company to make money"
-    - "This is for our Enterprise product line."
-    - "Here is my 1000 page design document that describes my idea"
-    - "I've been working on this for 6 months..."
-    - "Here's a 5000 line patch that..."
-    - "I rewrote all of the current mess, and here it is..."
-    - "I have a deadline, and this patch needs to be applied now."
-
-Another way the kernel community is different than most traditional
-software engineering work environments is the faceless nature of
-interaction.  One benefit of using email and irc as the primary forms of
-communication is the lack of discrimination based on gender or race.
-The Linux kernel work environment is accepting of women and minorities
-because all you are is an email address.  The international aspect also
-helps to level the playing field because you can't guess gender based on
-a person's name. A man may be named Andrea and a woman may be named Pat.
-Most women who have worked in the Linux kernel and have expressed an
-opinion have had positive experiences.
-
-The language barrier can cause problems for some people who are not
-comfortable with English.  A good grasp of the language can be needed in
-order to get ideas across properly on mailing lists, so it is
-recommended that you check your emails to make sure they make sense in
-English before sending them.
-
-
-Break up your changes
----------------------
-
-The Linux kernel community does not gladly accept large chunks of code
-dropped on it all at once.  The changes need to be properly introduced,
-discussed, and broken up into tiny, individual portions.  This is almost
-the exact opposite of what companies are used to doing.  Your proposal
-should also be introduced very early in the development process, so that
-you can receive feedback on what you are doing.  It also lets the
-community feel that you are working with them, and not simply using them
-as a dumping ground for your feature.  However, don't send 50 emails at
-one time to a mailing list, your patch series should be smaller than
-that almost all of the time.
-
-The reasons for breaking things up are the following:
-
-1) Small patches increase the likelihood that your patches will be
-   applied, since they don't take much time or effort to verify for
-   correctness.  A 5 line patch can be applied by a maintainer with
-   barely a second glance. However, a 500 line patch may take hours to
-   review for correctness (the time it takes is exponentially
-   proportional to the size of the patch, or something).
-
-   Small patches also make it very easy to debug when something goes
-   wrong.  It's much easier to back out patches one by one than it is
-   to dissect a very large patch after it's been applied (and broken
-   something).
-
-2) It's important not only to send small patches, but also to rewrite
-   and simplify (or simply re-order) patches before submitting them.
-
-Here is an analogy from kernel developer Al Viro:
-
-	*"Think of a teacher grading homework from a math student.  The
-	teacher does not want to see the student's trials and errors
-	before they came up with the solution. They want to see the
-	cleanest, most elegant answer.  A good student knows this, and
-	would never submit her intermediate work before the final
-	solution.*
-
-	*The same is true of kernel development. The maintainers and
-	reviewers do not want to see the thought process behind the
-	solution to the problem one is solving. They want to see a
-	simple and elegant solution."*
-
-It may be challenging to keep the balance between presenting an elegant
-solution and working together with the community and discussing your
-unfinished work. Therefore it is good to get early in the process to
-get feedback to improve your work, but also keep your changes in small
-chunks that they may get already accepted, even when your whole task is
-not ready for inclusion now.
-
-Also realize that it is not acceptable to send patches for inclusion
-that are unfinished and will be "fixed up later."
-
-
-Justify your change
--------------------
-
-Along with breaking up your patches, it is very important for you to let
-the Linux community know why they should add this change.  New features
-must be justified as being needed and useful.
-
-
-Document your change
---------------------
-
-When sending in your patches, pay special attention to what you say in
-the text in your email.  This information will become the ChangeLog
-information for the patch, and will be preserved for everyone to see for
-all time.  It should describe the patch completely, containing:
-
-  - why the change is necessary
-  - the overall design approach in the patch
-  - implementation details
-  - testing results
-
-For more details on what this should all look like, please see the
-ChangeLog section of the document:
-
-  "The Perfect Patch"
-      http://www.ozlabs.org/~akpm/stuff/tpp.txt
-
-
-All of these things are sometimes very hard to do. It can take years to
-perfect these practices (if at all). It's a continuous process of
-improvement that requires a lot of patience and determination. But
-don't give up, it's possible. Many have done it before, and each had to
-start exactly where you are now.
-
-
-
-
-----------
-
-Thanks to Paolo Ciarrocchi who allowed the "Development Process"
-(https://lwn.net/Articles/94386/) section
-to be based on text he had written, and to Randy Dunlap and Gerrit
-Huizenga for some of the list of things you should and should not say.
-Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
-Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi
-Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
-David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for
-their review, comments, and contributions.  Without their help, this
-document would not have been possible.
-
-
-
-Maintainer: Greg Kroah-Hartman <greg@kroah.com>
diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt
index c0d8788..7229230 100644
--- a/Documentation/IPMI.txt
+++ b/Documentation/IPMI.txt
@@ -111,6 +111,8 @@
 I2C kernel driver's SMBus interfaces to send and receive IPMI messages
 over the SMBus.
 
+ipmi_powernv - A driver for access BMCs on POWERNV systems.
+
 ipmi_watchdog - IPMI requires systems to have a very capable watchdog
 timer.  This driver implements the standard Linux watchdog timer
 interface on top of the IPMI message handler.
@@ -118,17 +120,15 @@
 ipmi_poweroff - Some systems support the ability to be turned off via
 IPMI commands.
 
-These are all individually selectable via configuration options.
+bt-bmc - This is not part of the main driver, but instead a driver for
+accessing a BMC-side interface of a BT interface.  It is used on BMCs
+running Linux to provide an interface to the host.
 
-Note that the KCS-only interface has been removed.  The af_ipmi driver
-is no longer supported and has been removed because it was impossible
-to do 32 bit emulation on 64-bit kernels with it.
+These are all individually selectable via configuration options.
 
 Much documentation for the interface is in the include files.  The
 IPMI include files are:
 
-net/af_ipmi.h - Contains the socket interface.
-
 linux/ipmi.h - Contains the user interface and IOCTL interface for IPMI.
 
 linux/ipmi_smi.h - Contains the interface for system management interfaces
@@ -245,6 +245,16 @@
 and the user should not have to care what type of SMI is below them.
 
 
+Watching For Interfaces
+
+When your code comes up, the IPMI driver may or may not have detected
+if IPMI devices exist.  So you might have to defer your setup until
+the device is detected, or you might be able to do it immediately.
+To handle this, and to allow for discovery, you register an SMI
+watcher with ipmi_smi_watcher_register() to iterate over interfaces
+and tell you when they come and go.
+
+
 Creating the User
 
 To user the message handler, you must first create a user using
@@ -263,7 +273,7 @@
 
 Messaging
 
-To send a message from kernel-land, the ipmi_request() call does
+To send a message from kernel-land, the ipmi_request_settime() call does
 pretty much all message handling.  Most of the parameter are
 self-explanatory.  However, it takes a "msgid" parameter.  This is NOT
 the sequence number of messages.  It is simply a long value that is
@@ -352,11 +362,12 @@
 The SI Driver
 -------------
 
-The SI driver allows up to 4 KCS or SMIC interfaces to be configured
-in the system.  By default, scan the ACPI tables for interfaces, and
-if it doesn't find any the driver will attempt to register one KCS
-interface at the spec-specified I/O port 0xca2 without interrupts.
-You can change this at module load time (for a module) with:
+The SI driver allows KCS, BT, and SMIC interfaces to be configured
+in the system.  It discovers interfaces through a host of different
+methods, depending on the system.
+
+You can specify up to four interfaces on the module load line and
+control some module parameters:
 
   modprobe ipmi_si.o type=<type1>,<type2>....
        ports=<port1>,<port2>... addrs=<addr1>,<addr2>...
@@ -367,7 +378,7 @@
        force_kipmid=<enable1>,<enable2>,...
        kipmid_max_busy_us=<ustime1>,<ustime2>,...
        unload_when_empty=[0|1]
-       trydefaults=[0|1] trydmi=[0|1] tryacpi=[0|1]
+       trydmi=[0|1] tryacpi=[0|1]
        tryplatform=[0|1] trypci=[0|1]
 
 Each of these except try... items is a list, the first item for the
@@ -386,10 +397,6 @@
 If you specify irqs as non-zero for an interface, the driver will
 attempt to use the given interrupt for the device.
 
-trydefaults sets whether the standard IPMI interface at 0xca2 and
-any interfaces specified by ACPE are tried.  By default, the driver
-tries it, set this value to zero to turn this off.
-
 The other try... items disable discovery by their corresponding
 names.  These are all enabled by default, set them to zero to disable
 them.  The tryplatform disables openfirmware.
@@ -434,7 +441,7 @@
 
   ipmi_si.type=<type1>,<type2>...
        ipmi_si.ports=<port1>,<port2>... ipmi_si.addrs=<addr1>,<addr2>...
-       ipmi_si.irqs=<irq1>,<irq2>... ipmi_si.trydefaults=[0|1]
+       ipmi_si.irqs=<irq1>,<irq2>...
        ipmi_si.regspacings=<sp1>,<sp2>,...
        ipmi_si.regsizes=<size1>,<size2>,...
        ipmi_si.regshifts=<shift1>,<shift2>,...
@@ -444,11 +451,6 @@
 
 It works the same as the module parameters of the same names.
 
-By default, the driver will attempt to detect any device specified by
-ACPI, and if none of those then a KCS device at the spec-specified
-0xca2.  If you want to turn this off, set the "trydefaults" option to
-false.
-
 If your IPMI interface does not support interrupts and is a KCS or
 SMIC interface, the IPMI driver will start a kernel thread for the
 interface to help speed things up.  This is a low-priority kernel
@@ -500,7 +502,8 @@
 	addr=<i2caddr1>[,<i2caddr2>[,...]]
 	adapter=<adapter1>[,<adapter2>[...]]
 	dbg=<flags1>,<flags2>...
-        slave_addrs=<addr1>,<addr2>,...
+	slave_addrs=<addr1>,<addr2>,...
+	tryacpi=[0|1] trydmi=[0|1]
 	[dbg_probe=1]
 
 The addresses are normal I2C addresses.  The adapter is the string
@@ -513,6 +516,9 @@
 The debug flags are bit flags for each BMC found, they are:
 IPMI messages: 1, driver state: 2, timing: 4, I2C probe: 8
 
+The tryxxx parameters can be used to disable detecting interfaces
+from various sources.
+
 Setting dbg_probe to 1 will enable debugging of the probing and
 detection process for BMCs on the SMBusses.
 
@@ -535,7 +541,8 @@
 	ipmi_ssif.adapter=<adapter1>[,<adapter2>[...]]
 	ipmi_ssif.dbg=<flags1>[,<flags2>[...]]
 	ipmi_ssif.dbg_probe=1
-        ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]]
+	ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]]
+	ipmi_ssif.tryacpi=[0|1] ipmi_ssif.trydmi=[0|1]
 
 These are the same options as on the module command line.
 
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index 92deea3..707c653 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -10,6 +10,8 @@
 SPHINX_CONF   = conf.py
 PAPER         =
 BUILDDIR      = $(obj)/output
+PDFLATEX      = xelatex
+LATEXOPTS     = -interaction=batchmode
 
 # User-friendly check for sphinx-build
 HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
@@ -29,7 +31,7 @@
 else # HAVE_SPHINX
 
 # User-friendly check for pdflatex
-HAVE_PDFLATEX := $(shell if which xelatex >/dev/null 2>&1; then echo 1; else echo 0; fi)
+HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -51,8 +53,8 @@
 # $5 reST source folder relative to $(srctree)/$(src),
 #    e.g. "media" for the linux-tv book-set at ./Documentation/media
 
-quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4);
-      cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\
+quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
+      cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2;\
 	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
 	$(SPHINXBUILD) \
 	-b $2 \
@@ -67,16 +69,19 @@
 	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
 
 latexdocs:
-ifeq ($(HAVE_PDFLATEX),0)
-	$(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
-	@echo "  SKIP    Sphinx $@ target."
-else # HAVE_PDFLATEX
 	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
-endif # HAVE_PDFLATEX
+
+ifeq ($(HAVE_PDFLATEX),0)
+
+pdfdocs:
+	$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
+	@echo "  SKIP    Sphinx $@ target."
+
+else # HAVE_PDFLATEX
 
 pdfdocs: latexdocs
-ifneq ($(HAVE_PDFLATEX),0)
-	$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex)
+	$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex;)
+
 endif # HAVE_PDFLATEX
 
 epubdocs:
@@ -93,6 +98,7 @@
 
 cleandocs:
 	$(Q)rm -rf $(BUILDDIR)
+	$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C Documentation/media clean
 
 endif # HAVE_SPHINX
 
diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle
deleted file mode 100644
index dea2e66c..0000000
--- a/Documentation/ManagementStyle
+++ /dev/null
@@ -1,288 +0,0 @@
-.. _managementstyle:
-
-Linux kernel management style
-=============================
-
-This is a short document describing the preferred (or made up, depending
-on who you ask) management style for the linux kernel.  It's meant to
-mirror the CodingStyle document to some degree, and mainly written to
-avoid answering [#f1]_  the same (or similar) questions over and over again.
-
-Management style is very personal and much harder to quantify than
-simple coding style rules, so this document may or may not have anything
-to do with reality.  It started as a lark, but that doesn't mean that it
-might not actually be true. You'll have to decide for yourself.
-
-Btw, when talking about "kernel manager", it's all about the technical
-lead persons, not the people who do traditional management inside
-companies.  If you sign purchase orders or you have any clue about the
-budget of your group, you're almost certainly not a kernel manager.
-These suggestions may or may not apply to you.
-
-First off, I'd suggest buying "Seven Habits of Highly Effective
-People", and NOT read it.  Burn it, it's a great symbolic gesture.
-
-.. [#f1] This document does so not so much by answering the question, but by
-  making it painfully obvious to the questioner that we don't have a clue
-  to what the answer is.
-
-Anyway, here goes:
-
-.. _decisions:
-
-1) Decisions
-------------
-
-Everybody thinks managers make decisions, and that decision-making is
-important.  The bigger and more painful the decision, the bigger the
-manager must be to make it.  That's very deep and obvious, but it's not
-actually true.
-
-The name of the game is to **avoid** having to make a decision.  In
-particular, if somebody tells you "choose (a) or (b), we really need you
-to decide on this", you're in trouble as a manager.  The people you
-manage had better know the details better than you, so if they come to
-you for a technical decision, you're screwed.  You're clearly not
-competent to make that decision for them.
-
-(Corollary:if the people you manage don't know the details better than
-you, you're also screwed, although for a totally different reason.
-Namely that you are in the wrong job, and that **they** should be managing
-your brilliance instead).
-
-So the name of the game is to **avoid** decisions, at least the big and
-painful ones.  Making small and non-consequential decisions is fine, and
-makes you look like you know what you're doing, so what a kernel manager
-needs to do is to turn the big and painful ones into small things where
-nobody really cares.
-
-It helps to realize that the key difference between a big decision and a
-small one is whether you can fix your decision afterwards.  Any decision
-can be made small by just always making sure that if you were wrong (and
-you **will** be wrong), you can always undo the damage later by
-backtracking.  Suddenly, you get to be doubly managerial for making
-**two** inconsequential decisions - the wrong one **and** the right one.
-
-And people will even see that as true leadership (*cough* bullshit
-*cough*).
-
-Thus the key to avoiding big decisions becomes to just avoiding to do
-things that can't be undone.  Don't get ushered into a corner from which
-you cannot escape.  A cornered rat may be dangerous - a cornered manager
-is just pitiful.
-
-It turns out that since nobody would be stupid enough to ever really let
-a kernel manager have huge fiscal responsibility **anyway**, it's usually
-fairly easy to backtrack.  Since you're not going to be able to waste
-huge amounts of money that you might not be able to repay, the only
-thing you can backtrack on is a technical decision, and there
-back-tracking is very easy: just tell everybody that you were an
-incompetent nincompoop, say you're sorry, and undo all the worthless
-work you had people work on for the last year.  Suddenly the decision
-you made a year ago wasn't a big decision after all, since it could be
-easily undone.
-
-It turns out that some people have trouble with this approach, for two
-reasons:
-
- - admitting you were an idiot is harder than it looks.  We all like to
-   maintain appearances, and coming out in public to say that you were
-   wrong is sometimes very hard indeed.
- - having somebody tell you that what you worked on for the last year
-   wasn't worthwhile after all can be hard on the poor lowly engineers
-   too, and while the actual **work** was easy enough to undo by just
-   deleting it, you may have irrevocably lost the trust of that
-   engineer.  And remember: "irrevocable" was what we tried to avoid in
-   the first place, and your decision ended up being a big one after
-   all.
-
-Happily, both of these reasons can be mitigated effectively by just
-admitting up-front that you don't have a friggin' clue, and telling
-people ahead of the fact that your decision is purely preliminary, and
-might be the wrong thing.  You should always reserve the right to change
-your mind, and make people very **aware** of that.  And it's much easier
-to admit that you are stupid when you haven't **yet** done the really
-stupid thing.
-
-Then, when it really does turn out to be stupid, people just roll their
-eyes and say "Oops, he did it again".
-
-This preemptive admission of incompetence might also make the people who
-actually do the work also think twice about whether it's worth doing or
-not.  After all, if **they** aren't certain whether it's a good idea, you
-sure as hell shouldn't encourage them by promising them that what they
-work on will be included.  Make them at least think twice before they
-embark on a big endeavor.
-
-Remember: they'd better know more about the details than you do, and
-they usually already think they have the answer to everything.  The best
-thing you can do as a manager is not to instill confidence, but rather a
-healthy dose of critical thinking on what they do.
-
-Btw, another way to avoid a decision is to plaintively just whine "can't
-we just do both?" and look pitiful.  Trust me, it works.  If it's not
-clear which approach is better, they'll eventually figure it out.  The
-answer may end up being that both teams get so frustrated by the
-situation that they just give up.
-
-That may sound like a failure, but it's usually a sign that there was
-something wrong with both projects, and the reason the people involved
-couldn't decide was that they were both wrong.  You end up coming up
-smelling like roses, and you avoided yet another decision that you could
-have screwed up on.
-
-
-2) People
----------
-
-Most people are idiots, and being a manager means you'll have to deal
-with it, and perhaps more importantly, that **they** have to deal with
-**you**.
-
-It turns out that while it's easy to undo technical mistakes, it's not
-as easy to undo personality disorders.  You just have to live with
-theirs - and yours.
-
-However, in order to prepare yourself as a kernel manager, it's best to
-remember not to burn any bridges, bomb any innocent villagers, or
-alienate too many kernel developers. It turns out that alienating people
-is fairly easy, and un-alienating them is hard. Thus "alienating"
-immediately falls under the heading of "not reversible", and becomes a
-no-no according to :ref:`decisions`.
-
-There's just a few simple rules here:
-
- (1) don't call people d*ckheads (at least not in public)
- (2) learn how to apologize when you forgot rule (1)
-
-The problem with #1 is that it's very easy to do, since you can say
-"you're a d*ckhead" in millions of different ways [#f2]_, sometimes without
-even realizing it, and almost always with a white-hot conviction that
-you are right.
-
-And the more convinced you are that you are right (and let's face it,
-you can call just about **anybody** a d*ckhead, and you often **will** be
-right), the harder it ends up being to apologize afterwards.
-
-To solve this problem, you really only have two options:
-
- - get really good at apologies
- - spread the "love" out so evenly that nobody really ends up feeling
-   like they get unfairly targeted.  Make it inventive enough, and they
-   might even be amused.
-
-The option of being unfailingly polite really doesn't exist. Nobody will
-trust somebody who is so clearly hiding his true character.
-
-.. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite
-  frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't
-  scan nearly as well.  But I'm sure he thought about it.
-
-
-3) People II - the Good Kind
-----------------------------
-
-While it turns out that most people are idiots, the corollary to that is
-sadly that you are one too, and that while we can all bask in the secure
-knowledge that we're better than the average person (let's face it,
-nobody ever believes that they're average or below-average), we should
-also admit that we're not the sharpest knife around, and there will be
-other people that are less of an idiot than you are.
-
-Some people react badly to smart people.  Others take advantage of them.
-
-Make sure that you, as a kernel maintainer, are in the second group.
-Suck up to them, because they are the people who will make your job
-easier. In particular, they'll be able to make your decisions for you,
-which is what the game is all about.
-
-So when you find somebody smarter than you are, just coast along.  Your
-management responsibilities largely become ones of saying "Sounds like a
-good idea - go wild", or "That sounds good, but what about xxx?".  The
-second version in particular is a great way to either learn something
-new about "xxx" or seem **extra** managerial by pointing out something the
-smarter person hadn't thought about.  In either case, you win.
-
-One thing to look out for is to realize that greatness in one area does
-not necessarily translate to other areas.  So you might prod people in
-specific directions, but let's face it, they might be good at what they
-do, and suck at everything else.  The good news is that people tend to
-naturally gravitate back to what they are good at, so it's not like you
-are doing something irreversible when you **do** prod them in some
-direction, just don't push too hard.
-
-
-4) Placing blame
-----------------
-
-Things will go wrong, and people want somebody to blame. Tag, you're it.
-
-It's not actually that hard to accept the blame, especially if people
-kind of realize that it wasn't **all** your fault.  Which brings us to the
-best way of taking the blame: do it for another guy. You'll feel good
-for taking the fall, he'll feel good about not getting blamed, and the
-guy who lost his whole 36GB porn-collection because of your incompetence
-will grudgingly admit that you at least didn't try to weasel out of it.
-
-Then make the developer who really screwed up (if you can find him) know
-**in_private** that he screwed up.  Not just so he can avoid it in the
-future, but so that he knows he owes you one.  And, perhaps even more
-importantly, he's also likely the person who can fix it.  Because, let's
-face it, it sure ain't you.
-
-Taking the blame is also why you get to be manager in the first place.
-It's part of what makes people trust you, and allow you the potential
-glory, because you're the one who gets to say "I screwed up".  And if
-you've followed the previous rules, you'll be pretty good at saying that
-by now.
-
-
-5) Things to avoid
-------------------
-
-There's one thing people hate even more than being called "d*ckhead",
-and that is being called a "d*ckhead" in a sanctimonious voice.  The
-first you can apologize for, the second one you won't really get the
-chance.  They likely will no longer be listening even if you otherwise
-do a good job.
-
-We all think we're better than anybody else, which means that when
-somebody else puts on airs, it **really** rubs us the wrong way.  You may
-be morally and intellectually superior to everybody around you, but
-don't try to make it too obvious unless you really **intend** to irritate
-somebody [#f3]_.
-
-Similarly, don't be too polite or subtle about things. Politeness easily
-ends up going overboard and hiding the problem, and as they say, "On the
-internet, nobody can hear you being subtle". Use a big blunt object to
-hammer the point in, because you can't really depend on people getting
-your point otherwise.
-
-Some humor can help pad both the bluntness and the moralizing.  Going
-overboard to the point of being ridiculous can drive a point home
-without making it painful to the recipient, who just thinks you're being
-silly.  It can thus help get through the personal mental block we all
-have about criticism.
-
-.. [#f3] Hint: internet newsgroups that are not directly related to your work
-  are great ways to take out your frustrations at other people. Write
-  insulting posts with a sneer just to get into a good flame every once in
-  a while, and you'll feel cleansed. Just don't crap too close to home.
-
-
-6) Why me?
-----------
-
-Since your main responsibility seems to be to take the blame for other
-peoples mistakes, and make it painfully obvious to everybody else that
-you're incompetent, the obvious question becomes one of why do it in the
-first place?
-
-First off, while you may or may not get screaming teenage girls (or
-boys, let's not be judgmental or sexist here) knocking on your dressing
-room door, you **will** get an immense feeling of personal accomplishment
-for being "in charge".  Never mind the fact that you're really leading
-by trying to keep up with everybody else and running after them as fast
-as you can.  Everybody will still think you're the person in charge.
-
-It's a great job if you can hack it.
diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html
index a4d3838..39bcb74 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.html
+++ b/Documentation/RCU/Design/Requirements/Requirements.html
@@ -547,7 +547,7 @@
 	It could reuse a value formerly fetched from this same pointer.
 	It could also fetch the pointer from <tt>gp</tt> in a byte-at-a-time
 	manner, resulting in <i>load tearing</i>, in turn resulting a bytewise
-	mash-up of two distince pointer values.
+	mash-up of two distinct pointer values.
 	It might even use value-speculation optimizations, where it makes
 	a wrong guess, but by the time it gets around to checking the
 	value, an update has changed the pointer to match the wrong guess.
@@ -659,6 +659,29 @@
 	In other words, a given instance of <tt>synchronize_rcu()</tt>
 	can avoid waiting on a given RCU read-side critical section only
 	if it can prove that <tt>synchronize_rcu()</tt> started first.
+
+	<p>
+	A related question is &ldquo;When <tt>rcu_read_lock()</tt>
+	doesn't generate any code, why does it matter how it relates
+	to a grace period?&rdquo;
+	The answer is that it is not the relationship of
+	<tt>rcu_read_lock()</tt> itself that is important, but rather
+	the relationship of the code within the enclosed RCU read-side
+	critical section to the code preceding and following the
+	grace period.
+	If we take this viewpoint, then a given RCU read-side critical
+	section begins before a given grace period when some access
+	preceding the grace period observes the effect of some access
+	within the critical section, in which case none of the accesses
+	within the critical section may observe the effects of any
+	access following the grace period.
+
+	<p>
+	As of late 2016, mathematical models of RCU take this
+	viewpoint, for example, see slides&nbsp;62 and&nbsp;63
+	of the
+	<a href="http://www2.rdrop.com/users/paulmck/scalability/paper/LinuxMM.2016.10.04c.LCE.pdf">2016 LinuxCon EU</a>
+	presentation.
 </font></td></tr>
 <tr><td>&nbsp;</td></tr>
 </table>
diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index 2044227..5cbd8b2 100644
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -237,7 +237,7 @@
 
 	The reader uses rcu_dereference() to fetch an RCU-protected
 	pointer, which returns a value that may then be safely
-	dereferenced.  Note that rcu_deference() does not actually
+	dereferenced.  Note that rcu_dereference() does not actually
 	dereference the pointer, instead, it protects the pointer for
 	later dereferencing.  It also executes any needed memory-barrier
 	instructions for a given CPU architecture.  Currently, only Alpha
diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs
deleted file mode 100644
index 342d769..0000000
--- a/Documentation/SecurityBugs
+++ /dev/null
@@ -1,46 +0,0 @@
-.. _securitybugs:
-
-Security bugs
-=============
-
-Linux kernel developers take security very seriously.  As such, we'd
-like to know when a security bug is found so that it can be fixed and
-disclosed as quickly as possible.  Please report security bugs to the
-Linux kernel security team.
-
-1) Contact
-----------
-
-The Linux kernel security team can be contacted by email at
-<security@kernel.org>.  This is a private list of security officers
-who will help verify the bug report and develop and release a fix.
-It is possible that the security team will bring in extra help from
-area maintainers to understand and fix the security vulnerability.
-
-As it is with any bug, the more information provided the easier it
-will be to diagnose and fix.  Please review the procedure outlined in
-REPORTING-BUGS if you are unclear about what information is helpful.
-Any exploit code is very helpful and will not be released without
-consent from the reporter unless it has already been made public.
-
-2) Disclosure
--------------
-
-The goal of the Linux kernel security team is to work with the
-bug submitter to bug resolution as well as disclosure.  We prefer
-to fully disclose the bug as soon as possible.  It is reasonable to
-delay disclosure when the bug or the fix is not yet fully understood,
-the solution is not well-tested or for vendor coordination.  However, we
-expect these delays to be short, measurable in days, not weeks or months.
-A disclosure date is negotiated by the security team working with the
-bug submitter as well as vendors.  However, the kernel security team
-holds the final say when setting a disclosure date.  The timeframe for
-disclosure is from immediate (esp. if it's already publicly known)
-to a few weeks.  As a basic default policy, we expect report date to
-disclosure date to be on the order of 7 days.
-
-3) Non-disclosure agreements
-----------------------------
-
-The Linux kernel security team is not a formal body and therefore unable
-to enter any non-disclosure agreements.
diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist
deleted file mode 100644
index 894289b..0000000
--- a/Documentation/SubmitChecklist
+++ /dev/null
@@ -1,120 +0,0 @@
-.. _submitchecklist:
-
-Linux Kernel patch submission checklist
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Here are some basic things that developers should do if they want to see their
-kernel patch submissions accepted more quickly.
-
-These are all above and beyond the documentation that is provided in
-:ref:`Documentation/SubmittingPatches <submittingpatches>`
-and elsewhere regarding submitting Linux kernel patches.
-
-
-1) If you use a facility then #include the file that defines/declares
-   that facility.  Don't depend on other header files pulling in ones
-   that you use.
-
-2) Builds cleanly:
-
-  a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and
-     ``=n``.  No ``gcc`` warnings/errors, no linker warnings/errors.
-
-  b) Passes ``allnoconfig``, ``allmodconfig``
-
-  c) Builds successfully when using ``O=builddir``
-
-3) Builds on multiple CPU architectures by using local cross-compile tools
-   or some other build farm.
-
-4) ppc64 is a good architecture for cross-compilation checking because it
-   tends to use ``unsigned long`` for 64-bit quantities.
-
-5) Check your patch for general style as detailed in
-   :ref:`Documentation/CodingStyle <codingstyle>`.
-   Check for trivial violations with the patch style checker prior to
-   submission (``scripts/checkpatch.pl``).
-   You should be able to justify all violations that remain in
-   your patch.
-
-6) Any new or modified ``CONFIG`` options don't muck up the config menu.
-
-7) All new ``Kconfig`` options have help text.
-
-8) Has been carefully reviewed with respect to relevant ``Kconfig``
-   combinations.  This is very hard to get right with testing -- brainpower
-   pays off here.
-
-9) Check cleanly with sparse.
-
-10) Use ``make checkstack`` and ``make namespacecheck`` and fix any problems
-    that they find.
-
-    .. note::
-
-       ``checkstack`` does not point out problems explicitly,
-       but any one function that uses more than 512 bytes on the stack is a
-       candidate for change.
-
-11) Include :ref:`kernel-doc <kernel_doc>` to document global  kernel APIs.
-    (Not required for static functions, but OK there also.) Use
-    ``make htmldocs`` or ``make pdfdocs`` to check the
-    :ref:`kernel-doc <kernel_doc>` and fix any issues.
-
-12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
-    ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
-    ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
-    ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all
-    simultaneously enabled.
-
-13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and
-    ``CONFIG_PREEMPT.``
-
-14) If the patch affects IO/Disk, etc: has been tested with and without
-    ``CONFIG_LBDAF.``
-
-15) All codepaths have been exercised with all lockdep features enabled.
-
-16) All new ``/proc`` entries are documented under ``Documentation/``
-
-17) All new kernel boot parameters are documented in
-    ``Documentation/kernel-parameters.txt``.
-
-18) All new module parameters are documented with ``MODULE_PARM_DESC()``
-
-19) All new userspace interfaces are documented in ``Documentation/ABI/``.
-    See ``Documentation/ABI/README`` for more information.
-    Patches that change userspace interfaces should be CCed to
-    linux-api@vger.kernel.org.
-
-20) Check that it all passes ``make headers_check``.
-
-21) Has been checked with injection of at least slab and page-allocation
-    failures.  See ``Documentation/fault-injection/``.
-
-    If the new code is substantial, addition of subsystem-specific fault
-    injection might be appropriate.
-
-22) Newly-added code has been compiled with ``gcc -W`` (use
-    ``make EXTRA_CFLAGS=-W``).  This will generate lots of noise, but is good
-    for finding bugs like "warning: comparison between signed and unsigned".
-
-23) Tested after it has been merged into the -mm patchset to make sure
-    that it still works with all of the other queued patches and various
-    changes in the VM, VFS, and other subsystems.
-
-24) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a
-    comment in the source code that explains the logic of what they are doing
-    and why.
-
-25) If any ioctl's are added by the patch, then also update
-    ``Documentation/ioctl/ioctl-number.txt``.
-
-26) If your modified source code depends on or uses any of the kernel
-    APIs or features that are related to the following ``Kconfig`` symbols,
-    then test multiple builds with the related ``Kconfig`` symbols disabled
-    and/or ``=m`` (if that option is available) [not all of these at the
-    same time, just various/random combinations of them]:
-
-    ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
-    ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``).
diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers
deleted file mode 100644
index 252b77a..0000000
--- a/Documentation/SubmittingDrivers
+++ /dev/null
@@ -1,183 +0,0 @@
-.. _submittingdrivers:
-
-Submitting Drivers For The Linux Kernel
-=======================================
-
-This document is intended to explain how to submit device drivers to the
-various kernel trees. Note that if you are interested in video card drivers
-you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org
-(http://x.org/) instead.
-
-Also read the Documentation/SubmittingPatches document.
-
-
-Allocating Device Numbers
--------------------------
-
-Major and minor numbers for block and character devices are allocated
-by the Linux assigned name and number authority (currently this is
-Torben Mathiasen). The site is http://www.lanana.org/. This
-also deals with allocating numbers for devices that are not going to
-be submitted to the mainstream kernel.
-See Documentation/devices.txt for more information on this.
-
-If you don't use assigned numbers then when your device is submitted it will
-be given an assigned number even if that is different from values you may
-have shipped to customers before.
-
-Who To Submit Drivers To
-------------------------
-
-Linux 2.0:
-	No new drivers are accepted for this kernel tree.
-
-Linux 2.2:
-	No new drivers are accepted for this kernel tree.
-
-Linux 2.4:
-	If the code area has a general maintainer then please submit it to
-	the maintainer listed in MAINTAINERS in the kernel file. If the
-	maintainer does not respond or you cannot find the appropriate
-	maintainer then please contact Willy Tarreau <w@1wt.eu>.
-
-Linux 2.6 and upper:
-	The same rules apply as 2.4 except that you should follow linux-kernel
-	to track changes in API's. The final contact point for Linux 2.6+
-	submissions is Andrew Morton.
-
-What Criteria Determine Acceptance
-----------------------------------
-
-Licensing:
-		The code must be released to us under the
-		GNU General Public License. We don't insist on any kind
-		of exclusive GPL licensing, and if you wish the driver
-		to be useful to other communities such as BSD you may well
-		wish to release under multiple licenses.
-		See accepted licenses at include/linux/module.h
-
-Copyright:
-		The copyright owner must agree to use of GPL.
-		It's best if the submitter and copyright owner
-		are the same person/entity. If not, the name of
-		the person/entity authorizing use of GPL should be
-		listed in case it's necessary to verify the will of
-		the copyright owner.
-
-Interfaces:
-		If your driver uses existing interfaces and behaves like
-		other drivers in the same class it will be much more likely
-		to be accepted than if it invents gratuitous new ones.
-		If you need to implement a common API over Linux and NT
-		drivers do it in userspace.
-
-Code:
-		Please use the Linux style of code formatting as documented
-		in :ref:`Documentation/CodingStyle <codingStyle>`.
-		If you have sections of code
-		that need to be in other formats, for example because they
-		are shared with a windows driver kit and you want to
-		maintain them just once separate them out nicely and note
-		this fact.
-
-Portability:
-		Pointers are not always 32bits, not all computers are little
-		endian, people do not all have floating point and you
-		shouldn't use inline x86 assembler in your driver without
-		careful thought. Pure x86 drivers generally are not popular.
-		If you only have x86 hardware it is hard to test portability
-		but it is easy to make sure the code can easily be made
-		portable.
-
-Clarity:
-		It helps if anyone can see how to fix the driver. It helps
-		you because you get patches not bug reports. If you submit a
-		driver that intentionally obfuscates how the hardware works
-		it will go in the bitbucket.
-
-PM support:
-		Since Linux is used on many portable and desktop systems, your
-		driver is likely to be used on such a system and therefore it
-		should support basic power management by implementing, if
-		necessary, the .suspend and .resume methods used during the
-		system-wide suspend and resume transitions.  You should verify
-		that your driver correctly handles the suspend and resume, but
-		if you are unable to ensure that, please at least define the
-		.suspend method returning the -ENOSYS ("Function not
-		implemented") error.  You should also try to make sure that your
-		driver uses as little power as possible when it's not doing
-		anything.  For the driver testing instructions see
-		Documentation/power/drivers-testing.txt and for a relatively
-		complete overview of the power management issues related to
-		drivers see Documentation/power/devices.txt .
-
-Control:
-		In general if there is active maintenance of a driver by
-		the author then patches will be redirected to them unless
-		they are totally obvious and without need of checking.
-		If you want to be the contact and update point for the
-		driver it is a good idea to state this in the comments,
-		and include an entry in MAINTAINERS for your driver.
-
-What Criteria Do Not Determine Acceptance
------------------------------------------
-
-Vendor:
-		Being the hardware vendor and maintaining the driver is
-		often a good thing. If there is a stable working driver from
-		other people already in the tree don't expect 'we are the
-		vendor' to get your driver chosen. Ideally work with the
-		existing driver author to build a single perfect driver.
-
-Author:
-		It doesn't matter if a large Linux company wrote the driver,
-		or you did. Nobody has any special access to the kernel
-		tree. Anyone who tells you otherwise isn't telling the
-		whole story.
-
-
-Resources
----------
-
-Linux kernel master tree:
-	ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/...
-
-	where *country_code* == your country code, such as
-	**us**, **uk**, **fr**, etc.
-
-	http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git
-
-Linux kernel mailing list:
-	linux-kernel@vger.kernel.org
-	[mail majordomo@vger.kernel.org to subscribe]
-
-Linux Device Drivers, Third Edition (covers 2.6.10):
-	http://lwn.net/Kernel/LDD3/  (free version)
-
-LWN.net:
-	Weekly summary of kernel development activity - http://lwn.net/
-
-	2.6 API changes:
-
-		http://lwn.net/Articles/2.6-kernel-api/
-
-	Porting drivers from prior kernels to 2.6:
-
-		http://lwn.net/Articles/driver-porting/
-
-KernelNewbies:
-	Documentation and assistance for new kernel programmers
-
-		http://kernelnewbies.org/
-
-Linux USB project:
-	http://www.linux-usb.org/
-
-How to NOT write kernel driver by Arjan van de Ven:
-	http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf
-
-Kernel Janitor:
-	http://kernelnewbies.org/KernelJanitors
-
-GIT, Fast Version Control System:
-	http://git-scm.com/
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 36f1ded..8145570 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -1,841 +1 @@
-.. _submittingpatches:
-
-How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
-=========================================================================================
-
-For a person or company who wishes to submit a change to the Linux
-kernel, the process can sometimes be daunting if you're not familiar
-with "the system."  This text is a collection of suggestions which
-can greatly increase the chances of your change being accepted.
-
-This document contains a large number of suggestions in a relatively terse
-format.  For detailed information on how the kernel development process
-works, see :ref:`Documentation/development-process <development_process_main>`.
-Also, read :ref:`Documentation/SubmitChecklist <submitchecklist>`
-for a list of items to check before
-submitting code.  If you are submitting a driver, also read
-:ref:`Documentation/SubmittingDrivers <submittingdrivers>`;
-for device tree binding patches, read
-Documentation/devicetree/bindings/submitting-patches.txt.
-
-Many of these steps describe the default behavior of the ``git`` version
-control system; if you use ``git`` to prepare your patches, you'll find much
-of the mechanical work done for you, though you'll still need to prepare
-and document a sensible set of patches.  In general, use of ``git`` will make
-your life as a kernel developer easier.
-
-Creating and Sending your Change
-********************************
-
-
-0) Obtain a current source tree
--------------------------------
-
-If you do not have a repository with the current kernel source handy, use
-``git`` to obtain one.  You'll want to start with the mainline repository,
-which can be grabbed with::
-
-  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-
-Note, however, that you may not want to develop against the mainline tree
-directly.  Most subsystem maintainers run their own trees and want to see
-patches prepared against those trees.  See the **T:** entry for the subsystem
-in the MAINTAINERS file to find that tree, or simply ask the maintainer if
-the tree is not listed there.
-
-It is still possible to download kernel releases via tarballs (as described
-in the next section), but that is the hard way to do kernel development.
-
-1) ``diff -up``
----------------
-
-If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN``
-to create patches.  Git generates patches in this form by default; if
-you're using ``git``, you can skip this section entirely.
-
-All changes to the Linux kernel occur in the form of patches, as
-generated by :manpage:`diff(1)`.  When creating your patch, make sure to
-create it in "unified diff" format, as supplied by the ``-u`` argument
-to :manpage:`diff(1)`.
-Also, please use the ``-p`` argument which shows which C function each
-change is in - that makes the resultant ``diff`` a lot easier to read.
-Patches should be based in the root kernel source directory,
-not in any lower subdirectory.
-
-To create a patch for a single file, it is often sufficient to do::
-
-	SRCTREE= linux
-	MYFILE=  drivers/net/mydriver.c
-
-	cd $SRCTREE
-	cp $MYFILE $MYFILE.orig
-	vi $MYFILE	# make your change
-	cd ..
-	diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
-
-To create a patch for multiple files, you should unpack a "vanilla",
-or unmodified kernel source tree, and generate a ``diff`` against your
-own source tree.  For example::
-
-	MYSRC= /devel/linux
-
-	tar xvfz linux-3.19.tar.gz
-	mv linux-3.19 linux-3.19-vanilla
-	diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
-		linux-3.19-vanilla $MYSRC > /tmp/patch
-
-``dontdiff`` is a list of files which are generated by the kernel during
-the build process, and should be ignored in any :manpage:`diff(1)`-generated
-patch.
-
-Make sure your patch does not include any extra files which do not
-belong in a patch submission.  Make sure to review your patch -after-
-generating it with :manpage:`diff(1)`, to ensure accuracy.
-
-If your changes produce a lot of deltas, you need to split them into
-individual patches which modify things in logical stages; see
-:ref:`split_changes`.  This will facilitate review by other kernel developers,
-very important if you want your patch accepted.
-
-If you're using ``git``, ``git rebase -i`` can help you with this process.  If
-you're not using ``git``, ``quilt`` <http://savannah.nongnu.org/projects/quilt>
-is another popular alternative.
-
-.. _describe_changes:
-
-2) Describe your changes
-------------------------
-
-Describe your problem.  Whether your patch is a one-line bug fix or
-5000 lines of a new feature, there must be an underlying problem that
-motivated you to do this work.  Convince the reviewer that there is a
-problem worth fixing and that it makes sense for them to read past the
-first paragraph.
-
-Describe user-visible impact.  Straight up crashes and lockups are
-pretty convincing, but not all bugs are that blatant.  Even if the
-problem was spotted during code review, describe the impact you think
-it can have on users.  Keep in mind that the majority of Linux
-installations run kernels from secondary stable trees or
-vendor/product-specific trees that cherry-pick only specific patches
-from upstream, so include anything that could help route your change
-downstream: provoking circumstances, excerpts from dmesg, crash
-descriptions, performance regressions, latency spikes, lockups, etc.
-
-Quantify optimizations and trade-offs.  If you claim improvements in
-performance, memory consumption, stack footprint, or binary size,
-include numbers that back them up.  But also describe non-obvious
-costs.  Optimizations usually aren't free but trade-offs between CPU,
-memory, and readability; or, when it comes to heuristics, between
-different workloads.  Describe the expected downsides of your
-optimization so that the reviewer can weigh costs against benefits.
-
-Once the problem is established, describe what you are actually doing
-about it in technical detail.  It's important to describe the change
-in plain English for the reviewer to verify that the code is behaving
-as you intend it to.
-
-The maintainer will thank you if you write your patch description in a
-form which can be easily pulled into Linux's source code management
-system, ``git``, as a "commit log".  See :ref:`explicit_in_reply_to`.
-
-Solve only one problem per patch.  If your description starts to get
-long, that's a sign that you probably need to split up your patch.
-See :ref:`split_changes`.
-
-When you submit or resubmit a patch or patch series, include the
-complete patch description and justification for it.  Don't just
-say that this is version N of the patch (series).  Don't expect the
-subsystem maintainer to refer back to earlier patch versions or referenced
-URLs to find the patch description and put that into the patch.
-I.e., the patch (series) and its description should be self-contained.
-This benefits both the maintainers and reviewers.  Some reviewers
-probably didn't even receive earlier versions of the patch.
-
-Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
-instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
-to do frotz", as if you are giving orders to the codebase to change
-its behaviour.
-
-If the patch fixes a logged bug entry, refer to that bug entry by
-number and URL.  If the patch follows from a mailing list discussion,
-give a URL to the mailing list archive; use the https://lkml.kernel.org/
-redirector with a ``Message-Id``, to ensure that the links cannot become
-stale.
-
-However, try to make your explanation understandable without external
-resources.  In addition to giving a URL to a mailing list archive or
-bug, summarize the relevant points of the discussion that led to the
-patch as submitted.
-
-If you want to refer to a specific commit, don't just refer to the
-SHA-1 ID of the commit. Please also include the oneline summary of
-the commit, to make it easier for reviewers to know what it is about.
-Example::
-
-	Commit e21d2170f36602ae2708 ("video: remove unnecessary
-	platform_set_drvdata()") removed the unnecessary
-	platform_set_drvdata(), but left the variable "dev" unused,
-	delete it.
-
-You should also be sure to use at least the first twelve characters of the
-SHA-1 ID.  The kernel repository holds a *lot* of objects, making
-collisions with shorter IDs a real possibility.  Bear in mind that, even if
-there is no collision with your six-character ID now, that condition may
-change five years from now.
-
-If your patch fixes a bug in a specific commit, e.g. you found an issue using
-``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
-the SHA-1 ID, and the one line summary.  For example::
-
-	Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
-
-The following ``git config`` settings can be used to add a pretty format for
-outputting the above style in the ``git log`` or ``git show`` commands::
-
-	[core]
-		abbrev = 12
-	[pretty]
-		fixes = Fixes: %h (\"%s\")
-
-.. _split_changes:
-
-3) Separate your changes
-------------------------
-
-Separate each **logical change** into a separate patch.
-
-For example, if your changes include both bug fixes and performance
-enhancements for a single driver, separate those changes into two
-or more patches.  If your changes include an API update, and a new
-driver which uses that new API, separate those into two patches.
-
-On the other hand, if you make a single change to numerous files,
-group those changes into a single patch.  Thus a single logical change
-is contained within a single patch.
-
-The point to remember is that each patch should make an easily understood
-change that can be verified by reviewers.  Each patch should be justifiable
-on its own merits.
-
-If one patch depends on another patch in order for a change to be
-complete, that is OK.  Simply note **"this patch depends on patch X"**
-in your patch description.
-
-When dividing your change into a series of patches, take special care to
-ensure that the kernel builds and runs properly after each patch in the
-series.  Developers using ``git bisect`` to track down a problem can end up
-splitting your patch series at any point; they will not thank you if you
-introduce bugs in the middle.
-
-If you cannot condense your patch set into a smaller set of patches,
-then only post say 15 or so at a time and wait for review and integration.
-
-
-
-4) Style-check your changes
----------------------------
-
-Check your patch for basic style violations, details of which can be
-found in
-:ref:`Documentation/CodingStyle <codingstyle>`.
-Failure to do so simply wastes
-the reviewers time and will get your patch rejected, probably
-without even being read.
-
-One significant exception is when moving code from one file to
-another -- in this case you should not modify the moved code at all in
-the same patch which moves it.  This clearly delineates the act of
-moving the code and your changes.  This greatly aids review of the
-actual differences and allows tools to better track the history of
-the code itself.
-
-Check your patches with the patch style checker prior to submission
-(scripts/checkpatch.pl).  Note, though, that the style checker should be
-viewed as a guide, not as a replacement for human judgment.  If your code
-looks better with a violation then its probably best left alone.
-
-The checker reports at three levels:
- - ERROR: things that are very likely to be wrong
- - WARNING: things requiring careful review
- - CHECK: things requiring thought
-
-You should be able to justify all violations that remain in your
-patch.
-
-
-5) Select the recipients for your patch
----------------------------------------
-
-You should always copy the appropriate subsystem maintainer(s) on any patch
-to code that they maintain; look through the MAINTAINERS file and the
-source code revision history to see who those maintainers are.  The
-script scripts/get_maintainer.pl can be very useful at this step.  If you
-cannot find a maintainer for the subsystem you are working on, Andrew
-Morton (akpm@linux-foundation.org) serves as a maintainer of last resort.
-
-You should also normally choose at least one mailing list to receive a copy
-of your patch set.  linux-kernel@vger.kernel.org functions as a list of
-last resort, but the volume on that list has caused a number of developers
-to tune it out.  Look in the MAINTAINERS file for a subsystem-specific
-list; your patch will probably get more attention there.  Please do not
-spam unrelated lists, though.
-
-Many kernel-related lists are hosted on vger.kernel.org; you can find a
-list of them at http://vger.kernel.org/vger-lists.html.  There are
-kernel-related lists hosted elsewhere as well, though.
-
-Do not send more than 15 patches at once to the vger mailing lists!!!
-
-Linus Torvalds is the final arbiter of all changes accepted into the
-Linux kernel.  His e-mail address is <torvalds@linux-foundation.org>.
-He gets a lot of e-mail, and, at this point, very few patches go through
-Linus directly, so typically you should do your best to -avoid-
-sending him e-mail.
-
-If you have a patch that fixes an exploitable security bug, send that patch
-to security@kernel.org.  For severe bugs, a short embargo may be considered
-to allow distributors to get the patch out to users; in such cases,
-obviously, the patch should not be sent to any public lists.
-
-Patches that fix a severe bug in a released kernel should be directed
-toward the stable maintainers by putting a line like this::
-
-  Cc: stable@vger.kernel.org
-
-into the sign-off area of your patch (note, NOT an email recipient).  You
-should also read
-:ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
-in addition to this file.
-
-Note, however, that some subsystem maintainers want to come to their own
-conclusions on which patches should go to the stable trees.  The networking
-maintainer, in particular, would rather not see individual developers
-adding lines like the above to their patches.
-
-If changes affect userland-kernel interfaces, please send the MAN-PAGES
-maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
-least a notification of the change, so that some information makes its way
-into the manual pages.  User-space API changes should also be copied to
-linux-api@vger.kernel.org.
-
-For small patches you may want to CC the Trivial Patch Monkey
-trivial@kernel.org which collects "trivial" patches. Have a look
-into the MAINTAINERS file for its current manager.
-
-Trivial patches must qualify for one of the following rules:
-
-- Spelling fixes in documentation
-- Spelling fixes for errors which could break :manpage:`grep(1)`
-- Warning fixes (cluttering with useless warnings is bad)
-- Compilation fixes (only if they are actually correct)
-- Runtime fixes (only if they actually fix things)
-- Removing use of deprecated functions/macros
-- Contact detail and documentation fixes
-- Non-portable code replaced by portable code (even in arch-specific,
-  since people copy, as long as it's trivial)
-- Any fix by the author/maintainer of the file (ie. patch monkey
-  in re-transmission mode)
-
-
-
-6) No MIME, no links, no compression, no attachments.  Just plain text
-----------------------------------------------------------------------
-
-Linus and other kernel developers need to be able to read and comment
-on the changes you are submitting.  It is important for a kernel
-developer to be able to "quote" your changes, using standard e-mail
-tools, so that they may comment on specific portions of your code.
-
-For this reason, all patches should be submitted by e-mail "inline".
-
-.. warning::
-
-  Be wary of your editor's word-wrap corrupting your patch,
-  if you choose to cut-n-paste your patch.
-
-Do not attach the patch as a MIME attachment, compressed or not.
-Many popular e-mail applications will not always transmit a MIME
-attachment as plain text, making it impossible to comment on your
-code.  A MIME attachment also takes Linus a bit more time to process,
-decreasing the likelihood of your MIME-attached change being accepted.
-
-Exception:  If your mailer is mangling patches then someone may ask
-you to re-send them using MIME.
-
-See :ref:`Documentation/email-clients.txt <email_clients>`
-for hints about configuring your e-mail client so that it sends your patches
-untouched.
-
-7) E-mail size
---------------
-
-Large changes are not appropriate for mailing lists, and some
-maintainers.  If your patch, uncompressed, exceeds 300 kB in size,
-it is preferred that you store your patch on an Internet-accessible
-server, and provide instead a URL (link) pointing to your patch.  But note
-that if your patch exceeds 300 kB, it almost certainly needs to be broken up
-anyway.
-
-8) Respond to review comments
------------------------------
-
-Your patch will almost certainly get comments from reviewers on ways in
-which the patch can be improved.  You must respond to those comments;
-ignoring reviewers is a good way to get ignored in return.  Review comments
-or questions that do not lead to a code change should almost certainly
-bring about a comment or changelog entry so that the next reviewer better
-understands what is going on.
-
-Be sure to tell the reviewers what changes you are making and to thank them
-for their time.  Code review is a tiring and time-consuming process, and
-reviewers sometimes get grumpy.  Even in that case, though, respond
-politely and address the problems they have pointed out.
-
-
-9) Don't get discouraged - or impatient
----------------------------------------
-
-After you have submitted your change, be patient and wait.  Reviewers are
-busy people and may not get to your patch right away.
-
-Once upon a time, patches used to disappear into the void without comment,
-but the development process works more smoothly than that now.  You should
-receive comments within a week or so; if that does not happen, make sure
-that you have sent your patches to the right place.  Wait for a minimum of
-one week before resubmitting or pinging reviewers - possibly longer during
-busy times like merge windows.
-
-
-10) Include PATCH in the subject
---------------------------------
-
-Due to high e-mail traffic to Linus, and to linux-kernel, it is common
-convention to prefix your subject line with [PATCH].  This lets Linus
-and other kernel developers more easily distinguish patches from other
-e-mail discussions.
-
-
-
-11) Sign your work
-------------------
-
-To improve tracking of who did what, especially with patches that can
-percolate to their final resting place in the kernel through several
-layers of maintainers, we've introduced a "sign-off" procedure on
-patches that are being emailed around.
-
-The sign-off is a simple line at the end of the explanation for the
-patch, which certifies that you wrote it or otherwise have the right to
-pass it on as an open-source patch.  The rules are pretty simple: if you
-can certify the below:
-
-Developer's Certificate of Origin 1.1
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By making a contribution to this project, I certify that:
-
-        (a) The contribution was created in whole or in part by me and I
-            have the right to submit it under the open source license
-            indicated in the file; or
-
-        (b) The contribution is based upon previous work that, to the best
-            of my knowledge, is covered under an appropriate open source
-            license and I have the right under that license to submit that
-            work with modifications, whether created in whole or in part
-            by me, under the same open source license (unless I am
-            permitted to submit under a different license), as indicated
-            in the file; or
-
-        (c) The contribution was provided directly to me by some other
-            person who certified (a), (b) or (c) and I have not modified
-            it.
-
-        (d) I understand and agree that this project and the contribution
-            are public and that a record of the contribution (including all
-            personal information I submit with it, including my sign-off) is
-            maintained indefinitely and may be redistributed consistent with
-            this project or the open source license(s) involved.
-
-then you just add a line saying::
-
-	Signed-off-by: Random J Developer <random@developer.example.org>
-
-using your real name (sorry, no pseudonyms or anonymous contributions.)
-
-Some people also put extra tags at the end.  They'll just be ignored for
-now, but you can do this to mark internal company procedures or just
-point out some special detail about the sign-off.
-
-If you are a subsystem or branch maintainer, sometimes you need to slightly
-modify patches you receive in order to merge them, because the code is not
-exactly the same in your tree and the submitters'. If you stick strictly to
-rule (c), you should ask the submitter to rediff, but this is a totally
-counter-productive waste of time and energy. Rule (b) allows you to adjust
-the code, but then it is very impolite to change one submitter's code and
-make him endorse your bugs. To solve this problem, it is recommended that
-you add a line between the last Signed-off-by header and yours, indicating
-the nature of your changes. While there is nothing mandatory about this, it
-seems like prepending the description with your mail and/or name, all
-enclosed in square brackets, is noticeable enough to make it obvious that
-you are responsible for last-minute changes. Example::
-
-	Signed-off-by: Random J Developer <random@developer.example.org>
-	[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
-	Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
-
-This practice is particularly helpful if you maintain a stable branch and
-want at the same time to credit the author, track changes, merge the fix,
-and protect the submitter from complaints. Note that under no circumstances
-can you change the author's identity (the From header), as it is the one
-which appears in the changelog.
-
-Special note to back-porters: It seems to be a common and useful practice
-to insert an indication of the origin of a patch at the top of the commit
-message (just after the subject line) to facilitate tracking. For instance,
-here's what we see in a 3.x-stable release::
-
-  Date:   Tue Oct 7 07:26:38 2014 -0400
-
-    libata: Un-break ATA blacklist
-
-    commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
-
-And here's what might appear in an older kernel once a patch is backported::
-
-    Date:   Tue May 13 22:12:27 2008 +0200
-
-        wireless, airo: waitbusy() won't delay
-
-        [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
-
-Whatever the format, this information provides a valuable help to people
-tracking your trees, and to people trying to troubleshoot bugs in your
-tree.
-
-
-12) When to use Acked-by: and Cc:
----------------------------------
-
-The Signed-off-by: tag indicates that the signer was involved in the
-development of the patch, or that he/she was in the patch's delivery path.
-
-If a person was not directly involved in the preparation or handling of a
-patch but wishes to signify and record their approval of it then they can
-ask to have an Acked-by: line added to the patch's changelog.
-
-Acked-by: is often used by the maintainer of the affected code when that
-maintainer neither contributed to nor forwarded the patch.
-
-Acked-by: is not as formal as Signed-off-by:.  It is a record that the acker
-has at least reviewed the patch and has indicated acceptance.  Hence patch
-mergers will sometimes manually convert an acker's "yep, looks good to me"
-into an Acked-by: (but note that it is usually better to ask for an
-explicit ack).
-
-Acked-by: does not necessarily indicate acknowledgement of the entire patch.
-For example, if a patch affects multiple subsystems and has an Acked-by: from
-one subsystem maintainer then this usually indicates acknowledgement of just
-the part which affects that maintainer's code.  Judgement should be used here.
-When in doubt people should refer to the original discussion in the mailing
-list archives.
-
-If a person has had the opportunity to comment on a patch, but has not
-provided such comments, you may optionally add a ``Cc:`` tag to the patch.
-This is the only tag which might be added without an explicit action by the
-person it names - but it should indicate that this person was copied on the
-patch.  This tag documents that potentially interested parties
-have been included in the discussion.
-
-
-13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
---------------------------------------------------------------------------
-
-The Reported-by tag gives credit to people who find bugs and report them and it
-hopefully inspires them to help us again in the future.  Please note that if
-the bug was reported in private, then ask for permission first before using the
-Reported-by tag.
-
-A Tested-by: tag indicates that the patch has been successfully tested (in
-some environment) by the person named.  This tag informs maintainers that
-some testing has been performed, provides a means to locate testers for
-future patches, and ensures credit for the testers.
-
-Reviewed-by:, instead, indicates that the patch has been reviewed and found
-acceptable according to the Reviewer's Statement:
-
-Reviewer's statement of oversight
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By offering my Reviewed-by: tag, I state that:
-
-	 (a) I have carried out a technical review of this patch to
-	     evaluate its appropriateness and readiness for inclusion into
-	     the mainline kernel.
-
-	 (b) Any problems, concerns, or questions relating to the patch
-	     have been communicated back to the submitter.  I am satisfied
-	     with the submitter's response to my comments.
-
-	 (c) While there may be things that could be improved with this
-	     submission, I believe that it is, at this time, (1) a
-	     worthwhile modification to the kernel, and (2) free of known
-	     issues which would argue against its inclusion.
-
-	 (d) While I have reviewed the patch and believe it to be sound, I
-	     do not (unless explicitly stated elsewhere) make any
-	     warranties or guarantees that it will achieve its stated
-	     purpose or function properly in any given situation.
-
-A Reviewed-by tag is a statement of opinion that the patch is an
-appropriate modification of the kernel without any remaining serious
-technical issues.  Any interested reviewer (who has done the work) can
-offer a Reviewed-by tag for a patch.  This tag serves to give credit to
-reviewers and to inform maintainers of the degree of review which has been
-done on the patch.  Reviewed-by: tags, when supplied by reviewers known to
-understand the subject area and to perform thorough reviews, will normally
-increase the likelihood of your patch getting into the kernel.
-
-A Suggested-by: tag indicates that the patch idea is suggested by the person
-named and ensures credit to the person for the idea. Please note that this
-tag should not be added without the reporter's permission, especially if the
-idea was not posted in a public forum. That said, if we diligently credit our
-idea reporters, they will, hopefully, be inspired to help us again in the
-future.
-
-A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
-is used to make it easy to determine where a bug originated, which can help
-review a bug fix. This tag also assists the stable kernel team in determining
-which stable kernel versions should receive your fix. This is the preferred
-method for indicating a bug fixed by the patch. See :ref:`describe_changes`
-for more details.
-
-
-14) The canonical patch format
-------------------------------
-
-This section describes how the patch itself should be formatted.  Note
-that, if you have your patches stored in a ``git`` repository, proper patch
-formatting can be had with ``git format-patch``.  The tools cannot create
-the necessary text, though, so read the instructions below anyway.
-
-The canonical patch subject line is::
-
-    Subject: [PATCH 001/123] subsystem: summary phrase
-
-The canonical patch message body contains the following:
-
-  - A ``from`` line specifying the patch author (only needed if the person
-    sending the patch is not the author).
-
-  - An empty line.
-
-  - The body of the explanation, line wrapped at 75 columns, which will
-    be copied to the permanent changelog to describe this patch.
-
-  - The ``Signed-off-by:`` lines, described above, which will
-    also go in the changelog.
-
-  - A marker line containing simply ``---``.
-
-  - Any additional comments not suitable for the changelog.
-
-  - The actual patch (``diff`` output).
-
-The Subject line format makes it very easy to sort the emails
-alphabetically by subject line - pretty much any email reader will
-support that - since because the sequence number is zero-padded,
-the numerical and alphabetic sort is the same.
-
-The ``subsystem`` in the email's Subject should identify which
-area or subsystem of the kernel is being patched.
-
-The ``summary phrase`` in the email's Subject should concisely
-describe the patch which that email contains.  The ``summary
-phrase`` should not be a filename.  Do not use the same ``summary
-phrase`` for every patch in a whole patch series (where a ``patch
-series`` is an ordered sequence of multiple, related patches).
-
-Bear in mind that the ``summary phrase`` of your email becomes a
-globally-unique identifier for that patch.  It propagates all the way
-into the ``git`` changelog.  The ``summary phrase`` may later be used in
-developer discussions which refer to the patch.  People will want to
-google for the ``summary phrase`` to read discussion regarding that
-patch.  It will also be the only thing that people may quickly see
-when, two or three months later, they are going through perhaps
-thousands of patches using tools such as ``gitk`` or ``git log
---oneline``.
-
-For these reasons, the ``summary`` must be no more than 70-75
-characters, and it must describe both what the patch changes, as well
-as why the patch might be necessary.  It is challenging to be both
-succinct and descriptive, but that is what a well-written summary
-should do.
-
-The ``summary phrase`` may be prefixed by tags enclosed in square
-brackets: "Subject: [PATCH <tag>...] <summary phrase>".  The tags are
-not considered part of the summary phrase, but describe how the patch
-should be treated.  Common tags might include a version descriptor if
-the multiple versions of the patch have been sent out in response to
-comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for
-comments.  If there are four patches in a patch series the individual
-patches may be numbered like this: 1/4, 2/4, 3/4, 4/4.  This assures
-that developers understand the order in which the patches should be
-applied and that they have reviewed or applied all of the patches in
-the patch series.
-
-A couple of example Subjects::
-
-    Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
-    Subject: [PATCH v2 01/27] x86: fix eflags tracking
-
-The ``from`` line must be the very first line in the message body,
-and has the form:
-
-        From: Original Author <author@example.com>
-
-The ``from`` line specifies who will be credited as the author of the
-patch in the permanent changelog.  If the ``from`` line is missing,
-then the ``From:`` line from the email header will be used to determine
-the patch author in the changelog.
-
-The explanation body will be committed to the permanent source
-changelog, so should make sense to a competent reader who has long
-since forgotten the immediate details of the discussion that might
-have led to this patch.  Including symptoms of the failure which the
-patch addresses (kernel log messages, oops messages, etc.) is
-especially useful for people who might be searching the commit logs
-looking for the applicable patch.  If a patch fixes a compile failure,
-it may not be necessary to include _all_ of the compile failures; just
-enough that it is likely that someone searching for the patch can find
-it.  As in the ``summary phrase``, it is important to be both succinct as
-well as descriptive.
-
-The ``---`` marker line serves the essential purpose of marking for patch
-handling tools where the changelog message ends.
-
-One good use for the additional comments after the ``---`` marker is for
-a ``diffstat``, to show what files have changed, and the number of
-inserted and deleted lines per file.  A ``diffstat`` is especially useful
-on bigger patches.  Other comments relevant only to the moment or the
-maintainer, not suitable for the permanent changelog, should also go
-here.  A good example of such comments might be ``patch changelogs``
-which describe what has changed between the v1 and v2 version of the
-patch.
-
-If you are going to include a ``diffstat`` after the ``---`` marker, please
-use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from
-the top of the kernel source tree and don't use too much horizontal
-space (easily fit in 80 columns, maybe with some indentation).  (``git``
-generates appropriate diffstats by default.)
-
-See more details on the proper patch format in the following
-references.
-
-.. _explicit_in_reply_to:
-
-15) Explicit In-Reply-To headers
---------------------------------
-
-It can be helpful to manually add In-Reply-To: headers to a patch
-(e.g., when using ``git send-email``) to associate the patch with
-previous relevant discussion, e.g. to link a bug fix to the email with
-the bug report.  However, for a multi-patch series, it is generally
-best to avoid using In-Reply-To: to link to older versions of the
-series.  This way multiple versions of the patch don't become an
-unmanageable forest of references in email clients.  If a link is
-helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
-the cover email text) to link to an earlier version of the patch series.
-
-
-16) Sending ``git pull`` requests
----------------------------------
-
-If you have a series of patches, it may be most convenient to have the
-maintainer pull them directly into the subsystem repository with a
-``git pull`` operation.  Note, however, that pulling patches from a developer
-requires a higher degree of trust than taking patches from a mailing list.
-As a result, many subsystem maintainers are reluctant to take pull
-requests, especially from new, unknown developers.  If in doubt you can use
-the pull request as the cover letter for a normal posting of the patch
-series, giving the maintainer the option of using either.
-
-A pull request should have [GIT] or [PULL] in the subject line.  The
-request itself should include the repository name and the branch of
-interest on a single line; it should look something like::
-
-  Please pull from
-
-      git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
-
-  to get these changes:
-
-A pull request should also include an overall message saying what will be
-included in the request, a ``git shortlog`` listing of the patches
-themselves, and a ``diffstat`` showing the overall effect of the patch series.
-The easiest way to get all this information together is, of course, to let
-``git`` do it for you with the ``git request-pull`` command.
-
-Some maintainers (including Linus) want to see pull requests from signed
-commits; that increases their confidence that the request actually came
-from you.  Linus, in particular, will not pull from public hosting sites
-like GitHub in the absence of a signed tag.
-
-The first step toward creating such tags is to make a GNUPG key and get it
-signed by one or more core kernel developers.  This step can be hard for
-new developers, but there is no way around it.  Attending conferences can
-be a good way to find developers who can sign your key.
-
-Once you have prepared a patch series in ``git`` that you wish to have somebody
-pull, create a signed tag with ``git tag -s``.  This will create a new tag
-identifying the last commit in the series and containing a signature
-created with your private key.  You will also have the opportunity to add a
-changelog-style message to the tag; this is an ideal place to describe the
-effects of the pull request as a whole.
-
-If the tree the maintainer will be pulling from is not the repository you
-are working from, don't forget to push the signed tag explicitly to the
-public tree.
-
-When generating your pull request, use the signed tag as the target.  A
-command like this will do the trick::
-
-  git request-pull master git://my.public.tree/linux.git my-signed-tag
-
-
-REFERENCES
-**********
-
-Andrew Morton, "The perfect patch" (tpp).
-  <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
-
-Jeff Garzik, "Linux kernel patch submission format".
-  <http://linux.yyz.us/patch-format.html>
-
-Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
-  <http://www.kroah.com/log/linux/maintainer.html>
-
-  <http://www.kroah.com/log/linux/maintainer-02.html>
-
-  <http://www.kroah.com/log/linux/maintainer-03.html>
-
-  <http://www.kroah.com/log/linux/maintainer-04.html>
-
-  <http://www.kroah.com/log/linux/maintainer-05.html>
-
-  <http://www.kroah.com/log/linux/maintainer-06.html>
-
-NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
-  <https://lkml.org/lkml/2005/7/11/336>
-
-Kernel Documentation/CodingStyle:
-  :ref:`Documentation/CodingStyle <codingstyle>`
-
-Linus Torvalds's mail on the canonical patch format:
-  <http://lkml.org/lkml/2005/4/7/183>
-
-Andi Kleen, "On submitting kernel patches"
-  Some strategies to get difficult or controversial changes in.
-
-  http://halobates.de/on-submitting-patches.pdf
-
+This file has moved to process/submitting-patches.rst
diff --git a/Documentation/VGA-softcursor.txt b/Documentation/VGA-softcursor.txt
deleted file mode 100644
index 70acfbf..0000000
--- a/Documentation/VGA-softcursor.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-Software cursor for VGA    by Pavel Machek <pavel@atrey.karlin.mff.cuni.cz>
-=======================    and Martin Mares <mj@atrey.karlin.mff.cuni.cz>
-
-   Linux now has some ability to manipulate cursor appearance. Normally, you
-can set the size of hardware cursor (and also work around some ugly bugs in
-those miserable Trident cards--see #define TRIDENT_GLITCH in drivers/video/
-vgacon.c). You can now play a few new tricks:  you can make your cursor look
-like a non-blinking red block, make it inverse background of the character it's
-over or to highlight that character and still choose whether the original
-hardware cursor should remain visible or not.  There may be other things I have
-never thought of.
-
-   The cursor appearance is controlled by a "<ESC>[?1;2;3c" escape sequence
-where 1, 2 and 3 are parameters described below. If you omit any of them,
-they will default to zeroes.
-
-   Parameter 1 specifies cursor size (0=default, 1=invisible, 2=underline, ...,
-8=full block) + 16 if you want the software cursor to be applied + 32 if you
-want to always change the background color + 64 if you dislike having the
-background the same as the foreground.  Highlights are ignored for the last two
-flags.
-
-   The second parameter selects character attribute bits you want to change
-(by simply XORing them with the value of this parameter). On standard VGA,
-the high four bits specify background and the low four the foreground. In both
-groups, low three bits set color (as in normal color codes used by the console)
-and the most significant one turns on highlight (or sometimes blinking--it
-depends on the configuration of your VGA).
-
-   The third parameter consists of character attribute bits you want to set.
-Bit setting takes place before bit toggling, so you can simply clear a bit by 
-including it in both the set mask and the toggle mask.
-
-Examples:
-=========
-
-To get normal blinking underline, use: echo -e '\033[?2c'
-To get blinking block, use:            echo -e '\033[?6c'
-To get red non-blinking block, use:    echo -e '\033[?17;0;64c'
diff --git a/Documentation/acpi/DSD-properties-rules.txt b/Documentation/acpi/DSD-properties-rules.txt
new file mode 100644
index 0000000..3e4862b
--- /dev/null
+++ b/Documentation/acpi/DSD-properties-rules.txt
@@ -0,0 +1,97 @@
+_DSD Device Properties Usage Rules
+----------------------------------
+
+Properties, Property Sets and Property Subsets
+----------------------------------------------
+
+The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1,
+allows any type of device configuration data to be provided via the ACPI
+namespace.  In principle, the format of the data may be arbitrary, but it has to
+be identified by a UUID which must be recognized by the driver processing the
+_DSD output.  However, there are generic UUIDs defined for _DSD recognized by
+the ACPI subsystem in the Linux kernel which automatically processes the data
+packages associated with them and makes those data available to device drivers
+as "device properties".
+
+A device property is a data item consisting of a string key and a value (of a
+specific type) associated with it.
+
+In the ACPI _DSD context it is an element of the sub-package following the
+generic Device Properties UUID in the _DSD return package as specified in the
+Device Properties UUID definition document [1].
+
+It also may be regarded as the definition of a key and the associated data type
+that can be returned by _DSD in the Device Properties UUID sub-package for a
+given device.
+
+A property set is a collection of properties applicable to a hardware entity
+like a device.  In the ACPI _DSD context it is the set of all properties that
+can be returned in the Device Properties UUID sub-package for the device in
+question.
+
+Property subsets are nested collections of properties.  Each of them is
+associated with an additional key (name) allowing the subset to be referred
+to as a whole (and to be treated as a separate entity).  The canonical
+representation of property subsets is via the mechanism specified in the
+Hierarchical Properties Extension UUID definition document [2].
+
+Property sets may be hierarchical.  That is, a property set may contain
+multiple property subsets that each may contain property subsets of its
+own and so on.
+
+General Validity Rule for Property Sets
+---------------------------------------
+
+Valid property sets must follow the guidance given by the Device Properties UUID
+definition document [1].
+
+_DSD properties are intended to be used in addition to, and not instead of, the
+existing mechanisms defined by the ACPI specification.  Therefore, as a rule,
+they should only be used if the ACPI specification does not make direct
+provisions for handling the underlying use case.  It generally is invalid to
+return property sets which do not follow that rule from _DSD in data packages
+associated with the Device Properties UUID.
+
+Additional Considerations
+-------------------------
+
+There are cases in which, even if the general rule given above is followed in
+principle, the property set may still not be regarded as a valid one.
+
+For example, that applies to device properties which may cause kernel code
+(either a device driver or a library/subsystem) to access hardware in a way
+possibly leading to a conflict with AML methods in the ACPI namespace.  In
+particular, that may happen if the kernel code uses device properties to
+manipulate hardware normally controlled by ACPI methods related to power
+management, like _PSx and _DSW (for device objects) or _ON and _OFF (for power
+resource objects), or by ACPI device disabling/enabling methods, like _DIS and
+_SRS.
+
+In all cases in which kernel code may do something that will confuse AML as a
+result of using device properties, the device properties in question are not
+suitable for the ACPI environment and consequently they cannot belong to a valid
+property set.
+
+Property Sets and Device Tree Bindings
+--------------------------------------
+
+It often is useful to make _DSD return property sets that follow Device Tree
+bindings.
+
+In those cases, however, the above validity considerations must be taken into
+account in the first place and returning invalid property sets from _DSD must be
+avoided.  For this reason, it may not be possible to make _DSD return a property
+set following the given DT binding literally and completely.  Still, for the
+sake of code re-use, it may make sense to provide as much of the configuration
+data as possible in the form of device properties and complement that with an
+ACPI-specific mechanism suitable for the use case at hand.
+
+In any case, property sets following DT bindings literally should not be
+expected to automatically work in the ACPI environment regardless of their
+contents.
+
+References
+----------
+
+[1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
+[2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt
index a91ec5a..209a5eb 100644
--- a/Documentation/acpi/enumeration.txt
+++ b/Documentation/acpi/enumeration.txt
@@ -415,3 +415,12 @@
 ancestors provides a _DSD with a valid "compatible" property.  Such device
 objects are then simply regarded as additional "blocks" providing hierarchical
 configuration information to the driver of the composite ancestor device.
+
+However, PRP0001 can only be returned from either _HID or _CID of a device
+object if all of the properties returned by the _DSD associated with it (either
+the _DSD of the device object itself or the _DSD of its ancestor in the
+"composite device" case described above) can be used in the ACPI environment.
+Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
+property returned by it is meaningless.
+
+Refer to DSD-properties-rules.txt for more information.
diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.txt
index 5aafe0b3..2aff034 100644
--- a/Documentation/acpi/gpio-properties.txt
+++ b/Documentation/acpi/gpio-properties.txt
@@ -51,6 +51,68 @@
 In our Bluetooth example the "reset-gpios" refers to the second GpioIo()
 resource, second pin in that resource with the GPIO number of 31.
 
+It is possible to leave holes in the array of GPIOs. This is useful in
+cases like with SPI host controllers where some chip selects may be
+implemented as GPIOs and some as native signals. For example a SPI host
+controller can have chip selects 0 and 2 implemented as GPIOs and 1 as
+native:
+
+  Package () {
+      "cs-gpios",
+      Package () {
+          ^GPIO, 19, 0, 0, // chip select 0: GPIO
+          0,               // chip select 1: native signal
+          ^GPIO, 20, 0, 0, // chip select 2: GPIO
+      }
+  }
+
+Other supported properties
+--------------------------
+
+Following Device Tree compatible device properties are also supported by
+_DSD device properties for GPIO controllers:
+
+- gpio-hog
+- output-high
+- output-low
+- input
+- line-name
+
+Example:
+
+  Name (_DSD, Package () {
+      // _DSD Hierarchical Properties Extension UUID
+      ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+      Package () {
+          Package () {"hog-gpio8", "G8PU"}
+      }
+  })
+
+  Name (G8PU, Package () {
+      ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+      Package () {
+          Package () {"gpio-hog", 1},
+          Package () {"gpios", Package () {8, 0}},
+          Package () {"output-high", 1},
+          Package () {"line-name", "gpio8-pullup"},
+      }
+  })
+
+- gpio-line-names
+
+Example:
+
+  Package () {
+      "gpio-line-names",
+      Package () {
+          "SPI0_CS_N", "EXP2_INT", "MUX6_IO", "UART0_RXD", "MUX7_IO",
+          "LVL_C_A1", "MUX0_IO", "SPI1_MISO"
+      }
+  }
+
+See Documentation/devicetree/bindings/gpio/gpio.txt for more information
+about these properties.
+
 ACPI GPIO Mappings Provided by Drivers
 --------------------------------------
 
diff --git a/Documentation/acpi/osi.txt b/Documentation/acpi/osi.txt
new file mode 100644
index 0000000..50cde0c
--- /dev/null
+++ b/Documentation/acpi/osi.txt
@@ -0,0 +1,187 @@
+ACPI _OSI and _REV methods
+--------------------------
+
+An ACPI BIOS can use the "Operating System Interfaces" method (_OSI)
+to find out what the operating system supports. Eg. If BIOS
+AML code includes _OSI("XYZ"), the kernel's AML interpreter
+can evaluate that method, look to see if it supports 'XYZ'
+and answer YES or NO to the BIOS.
+
+The ACPI _REV method returns the "Revision of the ACPI specification
+that OSPM supports"
+
+This document explains how and why the BIOS and Linux should use these methods.
+It also explains how and why they are widely misused.
+
+How to use _OSI
+---------------
+
+Linux runs on two groups of machines -- those that are tested by the OEM
+to be compatible with Linux, and those that were never tested with Linux,
+but where Linux was installed to replace the original OS (Windows or OSX).
+
+The larger group is the systems tested to run only Windows.  Not only that,
+but many were tested to run with just one specific version of Windows.
+So even though the BIOS may use _OSI to query what version of Windows is running,
+only a single path through the BIOS has actually been tested.
+Experience shows that taking untested paths through the BIOS
+exposes Linux to an entire category of BIOS bugs.
+For this reason, Linux _OSI defaults must continue to claim compatibility
+with all versions of Windows.
+
+But Linux isn't actually compatible with Windows, and the Linux community
+has also been hurt with regressions when Linux adds the latest version of
+Windows to its list of _OSI strings.  So it is possible that additional strings
+will be more thoroughly vetted before shipping upstream in the future.
+But it is likely that they will all eventually be added.
+
+What should an OEM do if they want to support Linux and Windows
+using the same BIOS image?  Often they need to do something different
+for Linux to deal with how Linux is different from Windows.
+Here the BIOS should ask exactly what it wants to know:
+
+_OSI("Linux-OEM-my_interface_name")
+where 'OEM' is needed if this is an OEM-specific hook,
+and 'my_interface_name' describes the hook, which could be a
+quirk, a bug, or a bug-fix.
+
+In addition, the OEM should send a patch to upstream Linux
+via the linux-acpi@vger.kernel.org mailing list.  When that patch
+is checked into Linux, the OS will answer "YES" when the BIOS
+on the OEM's system uses _OSI to ask if the interface is supported
+by the OS.  Linux distributors can back-port that patch for Linux
+pre-installs, and it will be included by all distributions that
+re-base to upstream.  If the distribution can not update the kernel binary,
+they can also add an acpi_osi=Linux-OEM-my_interface_name
+cmdline parameter to the boot loader, as needed.
+
+If the string refers to a feature where the upstream kernel
+eventually grows support, a patch should be sent to remove
+the string when that support is added to the kernel.
+
+That was easy.  Read on, to find out how to do it wrong.
+
+Before _OSI, there was _OS
+--------------------------
+
+ACPI 1.0 specified "_OS" as an
+"object that evaluates to a string that identifies the operating system."
+
+The ACPI BIOS flow would include an evaluation of _OS, and the AML
+interpreter in the kernel would return to it a string identifying the OS:
+
+Windows 98, SE: "Microsoft Windows"
+Windows ME: "Microsoft WindowsME:Millenium Edition"
+Windows NT: "Microsoft Windows NT"
+
+The idea was on a platform tasked with running multiple OS's,
+the BIOS could use _OS to enable devices that an OS
+might support, or enable quirks or bug workarounds
+necessary to make the platform compatible with that pre-existing OS.
+
+But _OS had fundamental problems.  First, the BIOS needed to know the name
+of every possible version of the OS that would run on it, and needed to know
+all the quirks of those OS's.  Certainly it would make more sense
+for the BIOS to ask *specific* things of the OS, such
+"do you support a specific interface", and thus in ACPI 3.0,
+_OSI was born to replace _OS.
+
+_OS was abandoned, though even today, many BIOS look for
+_OS "Microsoft Windows NT", though it seems somewhat far-fetched
+that anybody would install those old operating systems
+over what came with the machine.
+
+Linux answers "Microsoft Windows NT" to please that BIOS idiom.
+That is the *only* viable strategy, as that is what modern Windows does,
+and so doing otherwise could steer the BIOS down an untested path.
+
+_OSI is born, and immediately misused
+--------------------------------------
+
+With _OSI, the *BIOS* provides the string describing an interface,
+and asks the OS: "YES/NO, are you compatible with this interface?"
+
+eg. _OSI("3.0 Thermal Model") would return TRUE if the OS knows how
+to deal with the thermal extensions made to the ACPI 3.0 specification.
+An old OS that doesn't know about those extensions would answer FALSE,
+and a new OS may be able to return TRUE.
+
+For an OS-specific interface, the ACPI spec said that the BIOS and the OS
+were to agree on a string of the form such as "Windows-interface_name".
+
+But two bad things happened.  First, the Windows ecosystem used _OSI
+not as designed, but as a direct replacement for _OS -- identifying
+the OS version, rather than an OS supported interface.  Indeed, right
+from the start, the ACPI 3.0 spec itself codified this misuse
+in example code using _OSI("Windows 2001").
+
+This misuse was adopted and continues today.
+
+Linux had no choice but to also return TRUE to _OSI("Windows 2001")
+and its successors.  To do otherwise would virtually guarantee breaking
+a BIOS that has been tested only with that _OSI returning TRUE.
+
+This strategy is problematic, as Linux is never completely compatible with
+the latest version of Windows, and sometimes it takes more than a year
+to iron out incompatibilities.
+
+Not to be out-done, the Linux community made things worse by returning TRUE
+to _OSI("Linux").  Doing so is even worse than the Windows misuse
+of _OSI, as "Linux" does not even contain any version information.
+_OSI("Linux") led to some BIOS' malfunctioning due to BIOS writer's
+using it in untested BIOS flows.  But some OEM's used _OSI("Linux")
+in tested flows to support real Linux features.  In 2009, Linux
+removed _OSI("Linux"), and added a cmdline parameter to restore it
+for legacy systems still needed it.  Further a BIOS_BUG warning prints
+for all BIOS's that invoke it.
+
+No BIOS should use _OSI("Linux").
+
+The result is a strategy for Linux to maximize compatibility with
+ACPI BIOS that are tested on Windows machines.  There is a real risk
+of over-stating that compatibility; but the alternative has often been
+catastrophic failure resulting from the BIOS taking paths that
+were never validated under *any* OS.
+
+Do not use _REV
+---------------
+
+Since _OSI("Linux") went away, some BIOS writers used _REV
+to support Linux and Windows differences in the same BIOS.
+
+_REV was defined in ACPI 1.0 to return the version of ACPI
+supported by the OS and the OS AML interpreter.
+
+Modern Windows returns _REV = 2.  Linux used ACPI_CA_SUPPORT_LEVEL,
+which would increment, based on the version of the spec supported.
+
+Unfortunately, _REV was also misused.  eg. some BIOS would check
+for _REV = 3, and do something for Linux, but when Linux returned
+_REV = 4, that support broke.
+
+In response to this problem, Linux returns _REV = 2 always,
+from mid-2015 onward.  The ACPI specification will also be updated
+to reflect that _REV is deprecated, and always returns 2.
+
+Apple Mac and _OSI("Darwin")
+----------------------------
+
+On Apple's Mac platforms, the ACPI BIOS invokes _OSI("Darwin")
+to determine if the machine is running Apple OSX.
+
+Like Linux's _OSI("*Windows*") strategy, Linux defaults to
+answering YES to _OSI("Darwin") to enable full access
+to the hardware and validated BIOS paths seen by OSX.
+Just like on Windows-tested platforms, this strategy has risks.
+
+Starting in Linux-3.18, the kernel answered YES to _OSI("Darwin")
+for the purpose of enabling Mac Thunderbolt support.  Further,
+if the kernel noticed _OSI("Darwin") being invoked, it additionally
+disabled all _OSI("*Windows*") to keep poorly written Mac BIOS
+from going down untested combinations of paths.
+
+The Linux-3.18 change in default caused power regressions on Mac
+laptops, and the 3.18 implementation did not allow changing
+the default via cmdline "acpi_osi=!Darwin".  Linux-4.7 fixed
+the ability to use acpi_osi=!Darwin as a workaround, and
+we hope to see Mac Thunderbolt power management support in Linux-4.11.
diff --git a/Documentation/acpi/video_extension.txt b/Documentation/acpi/video_extension.txt
index 78b32ac..79bf6a4 100644
--- a/Documentation/acpi/video_extension.txt
+++ b/Documentation/acpi/video_extension.txt
@@ -101,6 +101,6 @@
 not affect the sending of event to user space, they are always sent to user
 space regardless of whether or not the video module controls the backlight level
 directly. This behaviour can be controlled through the brightness_switch_enabled
-module parameter as documented in kernel-parameters.txt. It is recommended to
+module parameter as documented in admin-guide/kernel-parameters.rst. It is recommended to
 disable this behaviour once a GUI environment starts up and wants to have full
 control of the backlight level.
diff --git a/Documentation/adding-syscalls.txt b/Documentation/adding-syscalls.txt
deleted file mode 100644
index bbb31e0..0000000
--- a/Documentation/adding-syscalls.txt
+++ /dev/null
@@ -1,527 +0,0 @@
-Adding a New System Call
-========================
-
-This document describes what's involved in adding a new system call to the
-Linux kernel, over and above the normal submission advice in
-Documentation/SubmittingPatches.
-
-
-System Call Alternatives
-------------------------
-
-The first thing to consider when adding a new system call is whether one of
-the alternatives might be suitable instead.  Although system calls are the
-most traditional and most obvious interaction points between userspace and the
-kernel, there are other possibilities -- choose what fits best for your
-interface.
-
- - If the operations involved can be made to look like a filesystem-like
-   object, it may make more sense to create a new filesystem or device.  This
-   also makes it easier to encapsulate the new functionality in a kernel module
-   rather than requiring it to be built into the main kernel.
-     - If the new functionality involves operations where the kernel notifies
-       userspace that something has happened, then returning a new file
-       descriptor for the relevant object allows userspace to use
-       poll/select/epoll to receive that notification.
-     - However, operations that don't map to read(2)/write(2)-like operations
-       have to be implemented as ioctl(2) requests, which can lead to a
-       somewhat opaque API.
- - If you're just exposing runtime system information, a new node in sysfs
-   (see Documentation/filesystems/sysfs.txt) or the /proc filesystem may be
-   more appropriate.  However, access to these mechanisms requires that the
-   relevant filesystem is mounted, which might not always be the case (e.g.
-   in a namespaced/sandboxed/chrooted environment).  Avoid adding any API to
-   debugfs, as this is not considered a 'production' interface to userspace.
- - If the operation is specific to a particular file or file descriptor, then
-   an additional fcntl(2) command option may be more appropriate.  However,
-   fcntl(2) is a multiplexing system call that hides a lot of complexity, so
-   this option is best for when the new function is closely analogous to
-   existing fcntl(2) functionality, or the new functionality is very simple
-   (for example, getting/setting a simple flag related to a file descriptor).
- - If the operation is specific to a particular task or process, then an
-   additional prctl(2) command option may be more appropriate.  As with
-   fcntl(2), this system call is a complicated multiplexor so is best reserved
-   for near-analogs of existing prctl() commands or getting/setting a simple
-   flag related to a process.
-
-
-Designing the API: Planning for Extension
------------------------------------------
-
-A new system call forms part of the API of the kernel, and has to be supported
-indefinitely.  As such, it's a very good idea to explicitly discuss the
-interface on the kernel mailing list, and it's important to plan for future
-extensions of the interface.
-
-(The syscall table is littered with historical examples where this wasn't done,
-together with the corresponding follow-up system calls -- eventfd/eventfd2,
-dup2/dup3, inotify_init/inotify_init1,  pipe/pipe2, renameat/renameat2 -- so
-learn from the history of the kernel and plan for extensions from the start.)
-
-For simpler system calls that only take a couple of arguments, the preferred
-way to allow for future extensibility is to include a flags argument to the
-system call.  To make sure that userspace programs can safely use flags
-between kernel versions, check whether the flags value holds any unknown
-flags, and reject the system call (with EINVAL) if it does:
-
-    if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3))
-        return -EINVAL;
-
-(If no flags values are used yet, check that the flags argument is zero.)
-
-For more sophisticated system calls that involve a larger number of arguments,
-it's preferred to encapsulate the majority of the arguments into a structure
-that is passed in by pointer.  Such a structure can cope with future extension
-by including a size argument in the structure:
-
-    struct xyzzy_params {
-        u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */
-        u32 param_1;
-        u64 param_2;
-        u64 param_3;
-    };
-
-As long as any subsequently added field, say param_4, is designed so that a
-zero value gives the previous behaviour, then this allows both directions of
-version mismatch:
-
- - To cope with a later userspace program calling an older kernel, the kernel
-   code should check that any memory beyond the size of the structure that it
-   expects is zero (effectively checking that param_4 == 0).