Merge branch 'master' into upstream-fixes

	- how to use PPro Memory Type Range Registers to increase performance.

mutex-design.txt

	- info on the generic mutex subsystem.

namespaces/

	- directory with various information about namespaces

nbd.txt

	- info on a TCP implementation of a network block device.

netlabel/

	    procfs-guide.xml writing_usb_driver.xml \

	    kernel-api.xml filesystems.xml lsm.xml usb.xml \

	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \

	    genericirq.xml s390-drivers.xml

	    genericirq.xml s390-drivers.xml uio-howto.xml

###

# The build process is as follows (targets):

</abstract>

<revhistory>

	<revision>

	<revnumber>0.4</revnumber>

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

	<authorinitials>hjk</authorinitials>

	<revremark>Removed section about uio_dummy.</revremark>

	</revision>

	<revision>

	<revnumber>0.3</revnumber>

	<date>2007-04-29</date>

	user space. This simplifies development and reduces the risk of

	serious bugs within a kernel module.

	</para>

	<para>

	Please note that UIO is not an universal driver interface. Devices

	that are already handled well by other kernel subsystems (like

	networking or serial or USB) are no candidates for an UIO driver.

	Hardware that is ideally suited for an UIO driver fulfills all of

	the following:

	</para>

<itemizedlist>

<listitem>

	<para>The device has memory that can be mapped. The device can be

	controlled completely by writing to this memory.</para>

</listitem>

<listitem>

	<para>The device usually generates interrupts.</para>

</listitem>

<listitem>

	<para>The device does not fit into one of the standard kernel

	subsystems.</para>

</listitem>

</itemizedlist>

</sect1>

<sect1 id="thanks">

	For cards that don't generate interrupts but need to be

	polled, there is the possibility to set up a timer that

	triggers the interrupt handler at configurable time intervals.

	See <filename>drivers/uio/uio_dummy.c</filename> for an

	example of this technique.

	This interrupt simulation is done by calling

	<function>uio_event_notify()</function>

	from the timer's event handler.

	</para>

	<para>

</sect1>

</chapter>

<chapter id="using-uio_dummy" xreflabel="Using uio_dummy">

<?dbhtml filename="using-uio_dummy.html"?>

<title>Using uio_dummy</title>

	<para>

	Well, there is no real use for uio_dummy. Its only purpose is

	to test most parts of the UIO system (everything except

	hardware interrupts), and to serve as an example for the

	kernel module that you will have to write yourself.

	</para>

<sect1 id="what_uio_dummy_does">

<title>What uio_dummy does</title>

	<para>

	The kernel module <filename>uio_dummy.ko</filename> creates a

	device that uses a timer to generate periodic interrupts. The

	interrupt handler does nothing but increment a counter. The

	driver adds two custom attributes, <varname>count</varname>

	and <varname>freq</varname>, that appear under

	<filename>/sys/devices/platform/uio_dummy/</filename>.

	</para>

	<para>

	The attribute <varname>count</varname> can be read and

	written.  The associated file

	<filename>/sys/devices/platform/uio_dummy/count</filename>

	appears as a normal text file and contains the total number of

	timer interrupts. If you look at it (e.g. using

	<function>cat</function>), you'll notice it is slowly counting

	up.

	</para>

	<para>

	The attribute <varname>freq</varname> can be read and written.

	The content of

	<filename>/sys/devices/platform/uio_dummy/freq</filename>

	represents the number of system timer ticks between two timer

	interrupts. The default value of <varname>freq</varname> is

	the value of the kernel variable <varname>HZ</varname>, which

	gives you an interval of one second. Lower values will

	increase the frequency. Try the following:

	</para>

<programlisting format="linespecific">

cd /sys/devices/platform/uio_dummy/

echo 100 > freq

</programlisting>

	<para>

	Use <function>cat count</function> to see how the interrupt

	frequency changes.

	</para>

</sect1>

</chapter>

<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module">

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

<title>Writing your own kernel module</title>

	<para>

	Please have a look at <filename>uio_dummy.c</filename> as an

	Please have a look at <filename>uio_cif.c</filename> as an

	example. The following paragraphs explain the different

	sections of this file.

	</para>

interrupt, it's your modules task to determine the irq number during

initialization. If you don't have a hardware generated interrupt but

want to trigger the interrupt handler in some other way, set

<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. The

uio_dummy module does this as it triggers the event mechanism in a timer

routine. If you had no interrupt at all, you could set

<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>.

If you had no interrupt at all, you could set

<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this

rarely makes sense.

</para></listitem>

		/ getpagesize();

	p = get_pages(pages);

	/* Initialize the virtqueue */

	vq->next = NULL;

	vq->last_avail_idx = 0;

	vq->dev = dev;

	/* Initialize the configuration. */

	vq->config.num = num_descs;

	vq->config.irq = devices.next_irq++;

	for (i = &dev->vq; *i; i = &(*i)->next);

	*i = vq;

	/* Link virtqueue back to device. */

	vq->dev = dev;

	/* Set the routine to call when the Guest does something to this

	 * virtqueue. */

	vq->handle_output = handle_output;

	dev->desc = new_dev_desc(type);

	dev->handle_input = handle_input;

	dev->name = name;

	dev->vq = NULL;

	return dev;

}

	Namespaces compatibility list

This document contains the information about the problems user

may have when creating tasks living in different namespaces.

Here's the summary. This matrix shows the known problems, that

occur when tasks share some namespace (the columns) while living

in different other namespaces (the rows):

	UTS	IPC	VFS	PID	User	Net

UTS	 X

IPC		 X	 1

VFS			 X

PID		 1	 1	 X

User		 2	 2		 X

Net						 X

1. Both the IPC and the PID namespaces provide IDs to address

   object inside the kernel. E.g. semaphore with IPCID or

   process group with pid.

   In both cases, tasks shouldn't try exposing this ID to some

   other task living in a different namespace via a shared filesystem

   or IPC shmem/message. The fact is that this ID is only valid

   within the namespace it was obtained in and may refer to some

   other object in another namespace.

2. Intentionally, two equal user IDs in different user namespaces

   should not be equal from the VFS point of view. In other

   words, user 10 in one user namespace shouldn't have the same

   access permissions to files, belonging to user 10 in another

   namespace.

   The same is true for the IPC namespaces being shared - two users

   from different user namespaces should not access the same IPC objects

   even having equal UIDs.

   But currently this is not so.