Merge branch 'master' into upstream

What:		devfs

Date:		July 2005

Date:		July 2005 (scheduled), finally removed in kernel v2.6.18

Contact:	Greg Kroah-Hartman <gregkh@suse.de>

Description:

	devfs has been unmaintained for a number of years, has unfixable

	races, contains a naming policy within the kernel that is

	against the LSB, and can be replaced by using udev.

	The files fs/devfs/*, include/linux/devfs_fs*.h will be removed,

	The files fs/devfs/*, include/linux/devfs_fs*.h were removed,

	along with the the assorted devfs function calls throughout the

	kernel tree.

Users:

What:		/sys/power/

Date:		August 2006

Contact:	Rafael J. Wysocki <rjw@sisk.pl>

Description:

		The /sys/power directory will contain files that will

		provide a unified interface to the power management

		subsystem.

What:		/sys/power/state

Date:		August 2006

Contact:	Rafael J. Wysocki <rjw@sisk.pl>

Description:

		The /sys/power/state file controls the system power state.

		Reading from this file returns what states are supported,

		which is hard-coded to 'standby' (Power-On Suspend), 'mem'

		(Suspend-to-RAM), and 'disk' (Suspend-to-Disk).

		Writing to this file one of these strings causes the system to

		transition into that state. Please see the file

		Documentation/power/states.txt for a description of each of

		these states.

What:		/sys/power/disk

Date:		August 2006

Contact:	Rafael J. Wysocki <rjw@sisk.pl>

Description:

		The /sys/power/disk file controls the operating mode of the

		suspend-to-disk mechanism.  Reading from this file returns

		the name of the method by which the system will be put to

		sleep on the next suspend.  There are four methods supported:

		'firmware' - means that the memory image will be saved to disk

		by some firmware, in which case we also assume that the

		firmware will handle the system suspend.

		'platform' - the memory image will be saved by the kernel and

		the system will be put to sleep by the platform driver (e.g.

		ACPI or other PM registers).

		'shutdown' - the memory image will be saved by the kernel and

		the system will be powered off.

		'reboot' - the memory image will be saved by the kernel and

		the system will be rebooted.

		The suspend-to-disk method may be chosen by writing to this

		file one of the accepted strings:

		'firmware'

		'platform'

		'shutdown'

		'reboot'

		It will only change to 'firmware' or 'platform' if the system

		supports that.

What:		/sys/power/image_size

Date:		August 2006

Contact:	Rafael J. Wysocki <rjw@sisk.pl>

Description:

		The /sys/power/image_size file controls the size of the image

		created by the suspend-to-disk mechanism.  It can be written a

		string representing a non-negative integer that will be used

		as an upper limit of the image size, in bytes.  The kernel's

		suspend-to-disk code will do its best to ensure the image size

		will not exceed this number.  However, if it turns out to be

		impossible, the kernel will try to suspend anyway using the

		smallest image possible.  In particular, if "0" is written to

		this file, the suspend image will be as small as possible.

		Reading from this file will display the current image size

		limit, which is set to 500 MB by default.

What:		/sys/power/pm_trace

Date:		August 2006

Contact:	Rafael J. Wysocki <rjw@sisk.pl>

Description:

		The /sys/power/pm_trace file controls the code which saves the

		last PM event point in the RTC across reboots, so that you can

		debug a machine that just hangs during suspend (or more

		commonly, during resume).  Namely, the RTC is only used to save

		the last PM event point if this file contains '1'.  Initially

		it contains '0' which may be changed to '1' by writing a

		string representing a nonzero integer into it.

		To use this debugging feature you should attempt to suspend

		the machine, then reboot it and run

		dmesg -s 1000000 | grep 'hash matches'

		CAUTION: Using it will cause your machine's real-time (CMOS)

		clock to be set to a random invalid time after a resume.

    <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 at the

    devices.  USB uses a tree structure, with the host as the

    root (the system's master), hubs as interior nodes, and

    peripheral devices as leaves (and slaves).

    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 part for

    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 the downstream type are the squarish type

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

    Software doesn't need to deal with distributed autoconfiguration

    since the pre-designated master node manages all that.

    At the electrical level, bus protocol overhead is reduced by

    eliminating arbitration and moving scheduling into host software.

    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

    <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, including high speed

    transfers and transaction translating hubs (used for USB 1.1

    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>USB support was added to Linux early in the 2.2 kernel series

    shortly before the 2.3 development forked off.  Updates

    from 2.3 were regularly folded back into 2.2 releases, bringing

    new features such as <filename>/sbin/hotplug</filename> support,

    more drivers, and more robustness.

    The 2.5 kernel series continued such improvements, and also

    worked on USB 2.0 support,

    higher performance,

    better consistency between host controller drivers,

    API simplification (to make bugs less likely),

    and providing internal "kerneldoc" documentation.

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

    Because the Linux 2.x USB support evolved to support mass market

    platforms such as Apple Macintosh or PC-compatible systems,

    it didn't address design concerns for those types of USB systems.

    So it can't be used inside mass-market PDAs, or other peripherals.

    USB device drivers running inside those Linux peripherals

    But USB device drivers running inside those peripherals

    don't do the same things as the ones running inside hosts,

    and so they've been given a different name:

    they're called <emphasis>gadget drivers</emphasis>.

    This document does not present gadget drivers.

    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>Within the kernel,

    host-side drivers for USB devices talk to the "usbcore" APIs.

    There are two types of public "usbcore" APIs, targetted at two different

    layers of USB driver.  Those are

    <emphasis>general purpose</emphasis> drivers, exposed through

    driver frameworks such as block, character, or network devices;

    and drivers that are <emphasis>part of the core</emphasis>,

    which are involved in managing a USB bus.

    Such core drivers include the <emphasis>hub</emphasis> driver,

    which manages trees of USB devices, and several different kinds

    of <emphasis>host controller driver (HCD)</emphasis>,

    <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>

    <itemizedlist>

	<listitem><para>USB supports four kinds of data transfer

	(control, bulk, interrupt, and isochronous).  Two transfer

	types use bandwidth as it's available (control and bulk),

	while the other two types of transfer (interrupt and isochronous)

	<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 that might be used.

	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 "interface", each

	<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></listitem>

	<listitem><para>The Linux USB API supports synchronous calls for

	control and bulk messaging.

	control and bulk messages.

	It also supports asynchnous calls for all kinds of data transfer,

	using request structures called "URBs" (USB Request Blocks).

	</para></listitem>

	    file in your Linux kernel sources.

	    </para>

	    <para>Otherwise the main use for this file from programs

	    is to poll() it to get notifications of usb devices

	    as they're plugged or unplugged.

	    To see what changed, you'd need to read the file and

	    compare "before" and "after" contents, scan the filesystem,

	    or see its hotplug event.

	    </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(&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>

  quilt trees:

    - USB, PCI, Driver Core, and I2C, Greg Kroah-Hartman <gregkh@suse.de>

	kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/

    - x86-64, partly i386, Andi Kleen <ak@suse.de>

        ftp.firstfloor.org:/pub/ak/x86_64/quilt/

Bug Reporting

-------------

		 64 = /dev/usb/rio500	Diamond Rio 500

		 65 = /dev/usb/usblcd	USBLCD Interface (info@usblcd.de)

		 66 = /dev/usb/cpad0	Synaptics cPad (mouse/LCD)

		 67 = /dev/usb/adutux0	1st Ontrak ADU device

		    ...

		 76 = /dev/usb/adutux10	10th Ontrak ADU device

		 96 = /dev/usb/hiddev0	1st USB HID device

		    ...

		111 = /dev/usb/hiddev15	16th USB HID device