Merge with rsync://fileserver/linux

Again, keep in mind that this list assumes you are already

functionally running a Linux 2.4 kernel.  Also, not all tools are

necessary on all systems; obviously, if you don't have any PCMCIA (PC

Card) hardware, for example, you probably needn't concern yourself

with pcmcia-cs.

necessary on all systems; obviously, if you don't have any ISDN

hardware, for example, you probably needn't concern yourself with

isdn4k-utils.

o  Gnu C                  2.95.3                  # gcc --version

o  Gnu make               3.79.1                  # make --version

o  jfsutils               1.1.3                   # fsck.jfs -V

o  reiserfsprogs          3.6.3                   # reiserfsck -V 2>&1|grep reiserfsprogs

o  xfsprogs               2.6.0                   # xfs_db -V

o  pcmciautils            004

o  pcmcia-cs              3.1.21                  # cardmgr -V

o  quota-tools            3.09                    # quota -V

o  PPP                    2.4.0                   # pppd --version

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 (see below). 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.

Pcmcia-cs

---------

PCMCIA (PC Card) support is now partially implemented in the main

kernel source.  Pay attention when you recompile your kernel ;-).

Also, be sure to upgrade to the latest pcmcia-cs release.

kernel source. The "pcmciautils" package (see above) replaces pcmcia-cs

for newest kernels.

Quota-tools

-----------

--------

o  <ftp://oss.sgi.com/projects/xfs/download/>

Pcmciautils

-----------

o  <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/>

Pcmcia-cs

---------

o  <ftp://pcmcia-cs.sourceforge.net/pub/pcmcia-cs/pcmcia-cs-3.1.21.tar.gz>

o  <http://pcmcia-cs.sourceforge.net/>

Quota-tools

----------

	Called from ata_bus_probe() and ata_bus_reset() error paths,

	as well as when unregistering from the SCSI module (rmmod, hot

	unplug).

	This function should do whatever needs to be done to take the

	port out of use.  In most cases, ata_port_disable() can be used

	as this hook.

	</para>

	<para>

	Called from ata_bus_probe() on a failed probe.

	Called from ata_bus_reset() on a failed bus reset.

	Called from ata_scsi_release().

	</para>

	</sect2>

	found.  Typically used to apply device-specific fixups prior to

	issue of SET FEATURES - XFER MODE, and prior to operation.

	</para>

	<para>

	Called by ata_device_add() after ata_dev_identify() determines

	a device is present.

	</para>

	<para>

	This entry may be specified as NULL in ata_port_operations.

	</para>

	</sect2>

	registers / DMA buffers.  ->tf_read() is called to read the

	hardware registers / DMA buffers, to obtain the current set of

	taskfile register values.

	Most drivers for taskfile-based hardware (PIO or MMIO) use

	ata_tf_load() and ata_tf_read() for these hooks.

	</para>

	</sect2>

	<para>

	causes an ATA command, previously loaded with

	->tf_load(), to be initiated in hardware.

	Most drivers for taskfile-based hardware use ata_exec_command()

	for this hook.

	</para>

	</sect2>

indicating whether or not it is OK to use DMA for the supplied PACKET

command.

	</para>

	<para>

	This hook may be specified as NULL, in which case libata will

	assume that atapi dma can be supported.

	</para>

	</sect2>

	Reads the Status/AltStatus/Error ATA shadow register from

	hardware.  On some hardware, reading the Status register has

	the side effect of clearing the interrupt condition.

	Most drivers for taskfile-based hardware use

	ata_check_status() for this hook.

	</para>

	<para>

	Note that because this is called from ata_device_add(), at

	least a dummy function that clears device interrupts must be

	provided for all drivers, even if the controller doesn't

	actually have a taskfile status register.

	</para>

	</sect2>

	available for use) on the ATA bus.  This generally has no

	meaning on FIS-based devices.

	</para>

	<para>

	Most drivers for taskfile-based hardware use

	ata_std_dev_select() for this hook.  Controllers which do not

	support second drives on a port (such as SATA contollers) will

	use ata_noop_dev_select().

	</para>

	</sect2>

	for device presence (PATA and SATA), typically a soft reset

	(SRST) will be performed.  Drivers typically use the helper

	functions ata_bus_reset() or sata_phy_reset() for this hook.

	Many SATA drivers use sata_phy_reset() or call it from within

	their own phy_reset() functions.

	</para>

	</sect2>

These hooks are typically either no-ops, or simply not implemented, in

FIS-based drivers.

	</para>

	<para>

Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup()

hook.  ata_bmdma_setup() will write the pointer to the PRD table to

the IDE PRD Table Address register, enable DMA in the DMA Command

register, and call exec_command() to begin the transfer.

	</para>

	<para>

Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start()

hook.  ata_bmdma_start() will write the ATA_DMA_START flag to the DMA

Command register.

	</para>

	<para>

Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop()

hook.  ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA

command register.

	</para>

	<para>

Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook.

	</para>

	</sect2>

	helper function ata_qc_issue_prot() for taskfile protocol-based

	dispatch.  More advanced drivers implement their own ->qc_issue.

	</para>

	<para>

	ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and

	->bmdma_start() as necessary to initiate a transfer.

	</para>

	</sect2>

	before the interrupt handler is registered, to be sure hardware

	is quiet.

	</para>

	<para>

	The second argument, dev_instance, should be cast to a pointer

	to struct ata_host_set.

	</para>

	<para>

	Most legacy IDE drivers use ata_interrupt() for the

	irq_handler hook, which scans all ports in the host_set,

	determines which queued command was active (if any), and calls

	ata_host_intr(ap,qc).

	</para>

	<para>

	Most legacy IDE drivers use ata_bmdma_irq_clear() for the

	irq_clear() hook, which simply clears the interrupt and error

	flags in the DMA status register.

	</para>

	</sect2>

	<para>

	Read and write standard SATA phy registers.  Currently only used

	if ->phy_reset hook called the sata_phy_reset() helper function.

	sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.

	</para>

	</sect2>

	->port_start() is called just after the data structures for each

	port are initialized.  Typically this is used to alloc per-port

	DMA buffers / tables / rings, enable DMA engines, and similar

	tasks.  

	tasks.  Some drivers also use this entry point as a chance to

	allocate driver-private memory for ap->private_data.

	</para>

	<para>

	Many drivers use ata_port_start() as this hook or call

	it from their own port_start() hooks.  ata_port_start()

	allocates space for a legacy IDE PRD table and returns.

	</para>

	<para>

	->port_stop() is called after ->host_stop().  It's sole function

	is to release DMA/memory resources, now that they are no longer

	actively being used.

	actively being used.  Many drivers also free driver-private

	data from port at this time.

	</para>

	<para>

	Many drivers use ata_port_stop() as this hook, which frees the

	PRD table.

	</para>

	<para>

	->host_stop() is called after all ->port_stop() calls

have completed.  The hook must finalize hardware shutdown, release DMA

and other resources, etc.

	This hook may be specified as NULL, in which case it is not called.

	</para>

	</sect2>

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

Major and minor numbers for block and character devices are allocated

by the Linux assigned name and number authority (currently better

known as H Peter Anvin). The site is http://www.lanana.org/. This

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 you device is submitted it will

get given an assigned number even if that is different from values you may

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

	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 Alan Cox <alan@lxorguk.ukuu.org.uk>

	maintainer then please contact the 2.2 kernel maintainer:

	Marc-Christian Petersen <m.c.p@wolk-project.de>.

Linux 2.4:

	The same rules apply as 2.2. The final contact point for Linux 2.4

Licensing:	The code must be released to us under the

		GNU General Public License. We don't insist on any kind

		of exclusively GPL licensing, and if you wish the driver

		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.

To create a patch for a single file, it is often sufficient to do:

	SRCTREE= linux-2.4

	SRCTREE= linux-2.6

	MYFILE=  drivers/net/mydriver.c

	cd $SRCTREE

or unmodified kernel source tree, and generate a diff against your

own source tree.  For example:

	MYSRC= /devel/linux-2.4

	MYSRC= /devel/linux-2.6

	tar xvfz linux-2.4.0-test11.tar.gz

	mv linux linux-vanilla

	wget http://www.moses.uklinux.net/patches/dontdiff

	diff -uprN -X dontdiff linux-vanilla $MYSRC > /tmp/patch

	rm -f dontdiff

	tar xvfz linux-2.6.12.tar.gz

	mv linux-2.6.12 linux-2.6.12-vanilla

	diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \

		linux-2.6.12-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 diff(1)-generated

patch.  dontdiff is maintained by Tigran Aivazian <tigran@veritas.com>

patch.  The "dontdiff" file is included in the kernel tree in

2.6.12 and later.  For earlier kernel versions, you can get it

from <http://www.xenotime.net/linux/doc/dontdiff>.

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-

If your changes produce a lot of deltas, you may want to look into

splitting them into individual patches which modify things in

logical stages, this will facilitate easier reviewing by other

logical stages.  This will facilitate easier reviewing by other

kernel developers, very important if you want your patch accepted.

There are a number of scripts which can aid in this;

There are a number of scripts which can aid in this:

Quilt:

http://savannah.nongnu.org/projects/quilt

Randy Dunlap's patch scripts:

http://developer.osdl.org/rddunlap/scripts/patching-scripts.tgz

http://www.xenotime.net/linux/scripts/patching-scripts-002.tar.gz

Andrew Morton's patch scripts:

http://www.zip.com.au/~akpm/linux/patches/patch-scripts-0.16

http://www.zip.com.au/~akpm/linux/patches/patch-scripts-0.20

2) Describe your changes.

 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)

URL: <http://www.kernel.org/pub/linux/kernel/people/rusty/trivial/>

point out some special detail about the sign-off. 

12) More references for submitting patches

Andrew Morton, "The perfect patch" (tpp).

  <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt>

Jeff Garzik, "Linux kernel patch submission format."

  <http://linux.yyz.us/patch-format.html>

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

SECTION 2 - HINTS, TIPS, AND TRICKS

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

4) Don't over-design.

Don't try to anticipate nebulous future cases which may or may not

be useful:  "Make it as simple as you can, and no simpler"

be useful:  "Make it as simple as you can, and no simpler."

Block io priorities

===================

Intro

-----

With the introduction of cfq v3 (aka cfq-ts or time sliced cfq), basic io

priorities is supported for reads on files. This enables users to io nice

processes or process groups, similar to what has been possible to cpu

scheduling for ages. This document mainly details the current possibilites

with cfq, other io schedulers do not support io priorities so far.

Scheduling classes

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

CFQ implements three generic scheduling classes that determine how io is

served for a process.

IOPRIO_CLASS_RT: This is the realtime io class. This scheduling class is given

higher priority than any other in the system, processes from this class are

given first access to the disk every time. Thus it needs to be used with some

care, one io RT process can starve the entire system. Within the RT class,

there are 8 levels of class data that determine exactly how much time this

process needs the disk for on each service. In the future this might change

to be more directly mappable to performance, by passing in a wanted data

rate instead.

IOPRIO_CLASS_BE: This is the best-effort scheduling class, which is the default

for any process that hasn't set a specific io priority. The class data

determines how much io bandwidth the process will get, it's directly mappable

to the cpu nice levels just more coarsely implemented. 0 is the highest

BE prio level, 7 is the lowest. The mapping between cpu nice level and io

nice level is determined as: io_nice = (cpu_nice + 20) / 5.

IOPRIO_CLASS_IDLE: This is the idle scheduling class, processes running at this

level only get io time when no one else needs the disk. The idle class has no

class data, since it doesn't really apply here.

Tools

-----

See below for a sample ionice tool. Usage:

# ionice -c<class> -n<level> -p<pid>

If pid isn't given, the current process is assumed. IO priority settings

are inherited on fork, so you can use ionice to start the process at a given

level:

# ionice -c2 -n0 /bin/ls

will run ls at the best-effort scheduling class at the highest priority.

For a running process, you can give the pid instead:

# ionice -c1 -n2 -p100

will change pid 100 to run at the realtime scheduling class, at priority 2.

---> snip ionice.c tool <---

#include <stdio.h>

#include <stdlib.h>

#include <errno.h>

#include <getopt.h>

#include <unistd.h>

#include <sys/ptrace.h>

#include <asm/unistd.h>

extern int sys_ioprio_set(int, int, int);

extern int sys_ioprio_get(int, int);

#if defined(__i386__)

#define __NR_ioprio_set		289

#define __NR_ioprio_get		290

#elif defined(__ppc__)

#define __NR_ioprio_set		273

#define __NR_ioprio_get		274

#elif defined(__x86_64__)

#define __NR_ioprio_set		251

#define __NR_ioprio_get		252

#elif defined(__ia64__)

#define __NR_ioprio_set		1274

#define __NR_ioprio_get		1275

#else

#error "Unsupported arch"

#endif

_syscall3(int, ioprio_set, int, which, int, who, int, ioprio);

_syscall2(int, ioprio_get, int, which, int, who);

enum {

	IOPRIO_CLASS_NONE,

	IOPRIO_CLASS_RT,

	IOPRIO_CLASS_BE,

	IOPRIO_CLASS_IDLE,

};

enum {

	IOPRIO_WHO_PROCESS = 1,

	IOPRIO_WHO_PGRP,

	IOPRIO_WHO_USER,

};

#define IOPRIO_CLASS_SHIFT	13

const char *to_prio[] = { "none", "realtime", "best-effort", "idle", };

int main(int argc, char *argv[])

{

	int ioprio = 4, set = 0, ioprio_class = IOPRIO_CLASS_BE;

	int c, pid = 0;

	while ((c = getopt(argc, argv, "+n:c:p:")) != EOF) {

		switch (c) {

		case 'n':

			ioprio = strtol(optarg, NULL, 10);

			set = 1;

			break;

		case 'c':

			ioprio_class = strtol(optarg, NULL, 10);

			set = 1;

			break;

		case 'p':

			pid = strtol(optarg, NULL, 10);

			break;

		}

	}

	switch (ioprio_class) {

		case IOPRIO_CLASS_NONE:

			ioprio_class = IOPRIO_CLASS_BE;

			break;

		case IOPRIO_CLASS_RT:

		case IOPRIO_CLASS_BE:

			break;

		case IOPRIO_CLASS_IDLE:

			ioprio = 7;

			break;

		default:

			printf("bad prio class %d\n", ioprio_class);

			return 1;

	}

	if (!set) {

		if (!pid && argv[optind])

			pid = strtol(argv[optind], NULL, 10);

		ioprio = ioprio_get(IOPRIO_WHO_PROCESS, pid);

		printf("pid=%d, %d\n", pid, ioprio);

		if (ioprio == -1)

			perror("ioprio_get");

		else {

			ioprio_class = ioprio >> IOPRIO_CLASS_SHIFT;

			ioprio = ioprio & 0xff;

			printf("%s: prio %d\n", to_prio[ioprio_class], ioprio);

		}

	} else {

		if (ioprio_set(IOPRIO_WHO_PROCESS, pid, ioprio | ioprio_class << IOPRIO_CLASS_SHIFT) == -1) {

			perror("ioprio_set");

			return 1;

		}

		if (argv[optind])

			execvp(argv[optind], &argv[optind]);

	}

	return 0;

}

---> snip ionice.c tool <---

March 11 2005, Jens Axboe <axboe@suse.de>