Merge branch 'linus' into tracing/urgent

N: Linus Torvalds

E: torvalds@linux-foundation.org

D: Original kernel hacker

S: 12725 SW Millikan Way, Suite 400

S: Beaverton, Oregon 97005

S: Portland, Oregon 97005

S: USA

N: Marcelo Tosatti

What:		/sys/dev

Date:		April 2008

KernelVersion:	2.6.26

Contact:	Dan Williams <dan.j.williams@intel.com>

Description:	The /sys/dev tree provides a method to look up the sysfs

		path for a device using the information returned from

		stat(2).  There are two directories, 'block' and 'char',

		beneath /sys/dev containing symbolic links with names of

		the form "<major>:<minor>".  These links point to the

		corresponding sysfs path for the given device.

		Example:

		$ readlink /sys/dev/block/8:32

		../../block/sdc

		Entries in /sys/dev/char and /sys/dev/block will be

		dynamically created and destroyed as devices enter and

		leave the system.

Users:		mdadm <linux-raid@vger.kernel.org>

could race with data DMA.  Mapping the memory used for completion

indications with DMA_ATTR_WRITE_BARRIER would prevent the race.

DMA_ATTR_WEAK_ORDERING

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

DMA_ATTR_WEAK_ORDERING specifies that reads and writes to the mapping

may be weakly ordered, that is that reads and writes may pass each other.

Since it is optional for platforms to implement DMA_ATTR_WEAK_ORDERING,

those that do not will simply ignore the attribute and exhibit default

behavior.

<!-- !Edrivers/usb/gadget/epautoconf.c -->

</sect1>

<sect1 id="composite"><title>Composite Device Framework</title>

<para>The core API is sufficient for writing drivers for composite

USB devices (with more than one function in a given configuration),

and also multi-configuration devices (also more than one function,

but not necessarily sharing a given configuration).

There is however an optional framework which makes it easier to

reuse and combine functions.

</para>

<para>Devices using this framework provide a <emphasis>struct

usb_composite_driver</emphasis>, which in turn provides one or

more <emphasis>struct usb_configuration</emphasis> instances.

Each such configuration includes at least one

<emphasis>struct usb_function</emphasis>, which packages a user

visible role such as "network link" or "mass storage device".

Management functions may also exist, such as "Device Firmware

Upgrade".

</para>

!Iinclude/linux/usb/composite.h

!Edrivers/usb/gadget/composite.c

</sect1>

<sect1 id="functions"><title>Composite Device Functions</title>

<para>At this writing, a few of the current gadget drivers have

been converted to this framework.

Near-term plans include converting all of them, except for "gadgetfs".

</para>

!Edrivers/usb/gadget/f_acm.c

!Edrivers/usb/gadget/f_serial.c

</sect1>

</chapter>

<chapter id="controllers"><title>Peripheral Controller Drivers</title>

    </affiliation>

</author>

<copyright>

	<year>2006-2008</year>

	<holder>Hans-Jürgen Koch.</holder>

</copyright>

<legalnotice>

<para>

This documentation is Free Software licensed under the terms of the

GPL version 2.

</para>

</legalnotice>

<pubdate>2006-12-11</pubdate>

<abstract>

</abstract>

<revhistory>

	<revision>

	<revnumber>0.5</revnumber>

	<date>2008-05-22</date>

	<authorinitials>hjk</authorinitials>

	<revremark>Added description of write() function.</revremark>

	</revision>

	<revision>

	<revnumber>0.4</revnumber>

	<date>2007-11-26</date>

</bookinfo>

<chapter id="aboutthisdoc">

<?dbhtml filename="about.html"?>

<?dbhtml filename="aboutthis.html"?>

<title>About this document</title>

<sect1 id="copyright">

<?dbhtml filename="copyright.html"?>

<title>Copyright and License</title>

<para>

      Copyright (c) 2006 by Hans-Jürgen Koch.</para>

<para>

This documentation is Free Software licensed under the terms of the

GPL version 2.

</para>

</sect1>

<sect1 id="translations">

<?dbhtml filename="translations.html"?>

<title>Translations</title>

	represents the total interrupt count. You can use this number

	to figure out if you missed some interrupts.

	</para>

	<para>

	For some hardware that has more than one interrupt source internally,

	but not separate IRQ mask and status registers, there might be

	situations where userspace cannot determine what the interrupt source

	was if the kernel handler disables them by writing to the chip's IRQ

	register. In such a case, the kernel has to disable the IRQ completely

	to leave the chip's register untouched. Now the userspace part can

	determine the cause of the interrupt, but it cannot re-enable

	interrupts. Another cornercase is chips where re-enabling interrupts

	is a read-modify-write operation to a combined IRQ status/acknowledge

	register. This would be racy if a new interrupt occurred

	simultaneously.

	</para>

	<para>

	To address these problems, UIO also implements a write() function. It

	is normally not used and can be ignored for hardware that has only a

	single interrupt source or has separate IRQ mask and status registers.

	If you need it, however, a write to <filename>/dev/uioX</filename>

	will call the <function>irqcontrol()</function> function implemented

	by the driver. You have to write a 32-bit value that is usually either

	0 or 1 to disable or enable interrupts. If a driver does not implement

	<function>irqcontrol()</function>, <function>write()</function> will

	return with <varname>-ENOSYS</varname>.

	</para>

	<para>

	To handle interrupts properly, your custom kernel module can

<function>open()</function>, you will probably also want a custom

<function>release()</function> function.

</para></listitem>

<listitem><para>

<varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on)

</varname>: Optional. If you need to be able to enable or disable

interrupts from userspace by writing to <filename>/dev/uioX</filename>,

you can implement this function. The parameter <varname>irq_on</varname>

will be 0 to disable interrupts and 1 to enable them.

</para></listitem>

</itemizedlist>

<para>