Merge branch 'upstream-linus' of master.kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6

            The Spidernet Device Driver

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

Written by Linas Vepstas <linas@austin.ibm.com>

Version of 7 June 2007

Abstract

========

This document sketches the structure of portions of the spidernet

device driver in the Linux kernel tree. The spidernet is a gigabit

ethernet device built into the Toshiba southbridge commonly used

in the SONY Playstation 3 and the IBM QS20 Cell blade.

The Structure of the RX Ring.

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

The receive (RX) ring is a circular linked list of RX descriptors,

together with three pointers into the ring that are used to manage its

contents.

The elements of the ring are called "descriptors" or "descrs"; they

describe the received data. This includes a pointer to a buffer

containing the received data, the buffer size, and various status bits.

There are three primary states that a descriptor can be in: "empty",

"full" and "not-in-use".  An "empty" or "ready" descriptor is ready

to receive data from the hardware. A "full" descriptor has data in it,

and is waiting to be emptied and processed by the OS. A "not-in-use"

descriptor is neither empty or full; it is simply not ready. It may

not even have a data buffer in it, or is otherwise unusable.

During normal operation, on device startup, the OS (specifically, the

spidernet device driver) allocates a set of RX descriptors and RX

buffers. These are all marked "empty", ready to receive data. This

ring is handed off to the hardware, which sequentially fills in the

buffers, and marks them "full". The OS follows up, taking the full

buffers, processing them, and re-marking them empty.

This filling and emptying is managed by three pointers, the "head"

and "tail" pointers, managed by the OS, and a hardware current

descriptor pointer (GDACTDPA). The GDACTDPA points at the descr

currently being filled. When this descr is filled, the hardware

marks it full, and advances the GDACTDPA by one.  Thus, when there is

flowing RX traffic, every descr behind it should be marked "full",

and everything in front of it should be "empty".  If the hardware

discovers that the current descr is not empty, it will signal an

interrupt, and halt processing.

The tail pointer tails or trails the hardware pointer. When the

hardware is ahead, the tail pointer will be pointing at a "full"

descr. The OS will process this descr, and then mark it "not-in-use",

and advance the tail pointer.  Thus, when there is flowing RX traffic,

all of the descrs in front of the tail pointer should be "full", and

all of those behind it should be "not-in-use". When RX traffic is not

flowing, then the tail pointer can catch up to the hardware pointer.

The OS will then note that the current tail is "empty", and halt

processing.

The head pointer (somewhat mis-named) follows after the tail pointer.

When traffic is flowing, then the head pointer will be pointing at

a "not-in-use" descr. The OS will perform various housekeeping duties

on this descr. This includes allocating a new data buffer and

dma-mapping it so as to make it visible to the hardware. The OS will

then mark the descr as "empty", ready to receive data. Thus, when there

is flowing RX traffic, everything in front of the head pointer should

be "not-in-use", and everything behind it should be "empty". If no

RX traffic is flowing, then the head pointer can catch up to the tail

pointer, at which point the OS will notice that the head descr is

"empty", and it will halt processing.

Thus, in an idle system, the GDACTDPA, tail and head pointers will

all be pointing at the same descr, which should be "empty". All of the

other descrs in the ring should be "empty" as well.

The show_rx_chain() routine will print out the the locations of the

GDACTDPA, tail and head pointers. It will also summarize the contents

of the ring, starting at the tail pointer, and listing the status

of the descrs that follow.

A typical example of the output, for a nearly idle system, might be

net eth1: Total number of descrs=256

net eth1: Chain tail located at descr=20

net eth1: Chain head is at 20

net eth1: HW curr desc (GDACTDPA) is at 21

net eth1: Have 1 descrs with stat=x40800101

net eth1: HW next desc (GDACNEXTDA) is at 22

net eth1: Last 255 descrs with stat=xa0800000

In the above, the hardware has filled in one descr, number 20. Both

head and tail are pointing at 20, because it has not yet been emptied.

Meanwhile, hw is pointing at 21, which is free.

The "Have nnn decrs" refers to the descr starting at the tail: in this

case, nnn=1 descr, starting at descr 20. The "Last nnn descrs" refers

to all of the rest of the descrs, from the last status change. The "nnn"

is a count of how many descrs have exactly the same status.

The status x4... corresponds to "full" and status xa... corresponds

to "empty". The actual value printed is RXCOMST_A.

In the device driver source code, a different set of names are

used for these same concepts, so that

"empty" == SPIDER_NET_DESCR_CARDOWNED == 0xa

"full"  == SPIDER_NET_DESCR_FRAME_END == 0x4

"not in use" == SPIDER_NET_DESCR_NOT_IN_USE == 0xf

The RX RAM full bug/feature

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

As long as the OS can empty out the RX buffers at a rate faster than

the hardware can fill them, there is no problem. If, for some reason,

the OS fails to empty the RX ring fast enough, the hardware GDACTDPA

pointer will catch up to the head, notice the not-empty condition,

ad stop. However, RX packets may still continue arriving on the wire.

The spidernet chip can save some limited number of these in local RAM.

When this local ram fills up, the spider chip will issue an interrupt

indicating this (GHIINT0STS will show ERRINT, and the GRMFLLINT bit

will be set in GHIINT1STS).  When the RX ram full condition occurs,

a certain bug/feature is triggered that has to be specially handled.

This section describes the special handling for this condition.

When the OS finally has a chance to run, it will empty out the RX ring.

In particular, it will clear the descriptor on which the hardware had

stopped. However, once the hardware has decided that a certain

descriptor is invalid, it will not restart at that descriptor; instead

it will restart at the next descr. This potentially will lead to a

deadlock condition, as the tail pointer will be pointing at this descr,

which, from the OS point of view, is empty; the OS will be waiting for

this descr to be filled. However, the hardware has skipped this descr,

and is filling the next descrs. Since the OS doesn't see this, there

is a potential deadlock, with the OS waiting for one descr to fill,

while the hardware is waiting for a different set of descrs to become

empty.

A call to show_rx_chain() at this point indicates the nature of the

problem. A typical print when the network is hung shows the following:

net eth1: Spider RX RAM full, incoming packets might be discarded!

net eth1: Total number of descrs=256

net eth1: Chain tail located at descr=255

net eth1: Chain head is at 255

net eth1: HW curr desc (GDACTDPA) is at 0

net eth1: Have 1 descrs with stat=xa0800000

net eth1: HW next desc (GDACNEXTDA) is at 1

net eth1: Have 127 descrs with stat=x40800101

net eth1: Have 1 descrs with stat=x40800001

net eth1: Have 126 descrs with stat=x40800101

net eth1: Last 1 descrs with stat=xa0800000

Both the tail and head pointers are pointing at descr 255, which is

marked xa... which is "empty". Thus, from the OS point of view, there

is nothing to be done. In particular, there is the implicit assumption

that everything in front of the "empty" descr must surely also be empty,

as explained in the last section. The OS is waiting for descr 255 to

become non-empty, which, in this case, will never happen.

The HW pointer is at descr 0. This descr is marked 0x4.. or "full".

Since its already full, the hardware can do nothing more, and thus has

halted processing. Notice that descrs 0 through 254 are all marked

"full", while descr 254 and 255 are empty. (The "Last 1 descrs" is

descr 254, since tail was at 255.) Thus, the system is deadlocked,

and there can be no forward progress; the OS thinks there's nothing

to do, and the hardware has nowhere to put incoming data.

This bug/feature is worked around with the spider_net_resync_head_ptr()

routine. When the driver receives RX interrupts, but an examination

of the RX chain seems to show it is empty, then it is probable that

the hardware has skipped a descr or two (sometimes dozens under heavy

network conditions). The spider_net_resync_head_ptr() subroutine will

search the ring for the next full descr, and the driver will resume

operations there.  Since this will leave "holes" in the ring, there

is also a spider_net_resync_tail_ptr() that will skip over such holes.

As of this writing, the spider_net_resync() strategy seems to work very

well, even under heavy network loads.

The TX ring

===========

The TX ring uses a low-watermark interrupt scheme to make sure that

the TX queue is appropriately serviced for large packet sizes.

For packet sizes greater than about 1KBytes, the kernel can fill

the TX ring quicker than the device can drain it. Once the ring

is full, the netdev is stopped. When there is room in the ring,

the netdev needs to be reawakened, so that more TX packets are placed

in the ring. The hardware can empty the ring about four times per jiffy,

so its not appropriate to wait for the poll routine to refill, since

the poll routine runs only once per jiffy.  The low-watermark mechanism

marks a descr about 1/4th of the way from the bottom of the queue, so

that an interrupt is generated when the descr is processed. This

interrupt wakes up the netdev, which can then refill the queue.

For large packets, this mechanism generates a relatively small number

of interrupts, about 1K/sec. For smaller packets, this will drop to zero

interrupts, as the hardware can empty the queue faster than the kernel

can fill it.

 ======= END OF DOCUMENT ========

RISCOM8 DRIVER

S:	Orphan

RTL818X WIRELESS DRIVER

P:	Michael Wu

M:	flamingice@sourmilk.net

P:	Andrea Merello

M:	andreamrl@tiscali.it

L:	linux-wireless@vger.kernel.org

W:	http://linuxwireless.org/

T:	git kernel.org:/pub/scm/linux/kernel/git/mwu/mac80211-drivers.git

S:	Maintained

S3 SAVAGE FRAMEBUFFER DRIVER

P:	Antonino Daplas

M:	adaplas@gmail.com

	  If you choose to build module, its name will be phantom. If unsure,

	  say N here.

config EEPROM_93CX6

	tristate "EEPROM 93CX6 support"

	---help---

	  This is a driver for the EEPROM chipsets 93c46 and 93c66.

	  The driver supports both read as well as write commands.

	  If unsure, say N.

	  If you are not sure, say Y here.

endmenu

obj-$(CONFIG_SGI_IOC4)		+= ioc4.o

obj-$(CONFIG_SONY_LAPTOP)	+= sony-laptop.o

obj-$(CONFIG_THINKPAD_ACPI)	+= thinkpad_acpi.o

obj-$(CONFIG_EEPROM_93CX6)	+= eeprom_93cx6.o

/*

	Copyright (C) 2004 - 2006 rt2x00 SourceForge Project

	<http://rt2x00.serialmonkey.com>

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

	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.

	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.

 */

/*

	Module: eeprom_93cx6

	Abstract: EEPROM reader routines for 93cx6 chipsets.

	Supported chipsets: 93c46 & 93c66.

 */

#include <linux/kernel.h>

#include <linux/module.h>

#include <linux/version.h>

#include <linux/delay.h>

#include <linux/eeprom_93cx6.h>

MODULE_AUTHOR("http://rt2x00.serialmonkey.com");

MODULE_VERSION("1.0");

MODULE_DESCRIPTION("EEPROM 93cx6 chip driver");

MODULE_LICENSE("GPL");

static inline void eeprom_93cx6_pulse_high(struct eeprom_93cx6 *eeprom)

{

	eeprom->reg_data_clock = 1;

	eeprom->register_write(eeprom);

	/*

	 * Add a short delay for the pulse to work.

	 * According to the specifications the "maximum minimum"

	 * time should be 450ns.

	 */

	ndelay(450);

}

static inline void eeprom_93cx6_pulse_low(struct eeprom_93cx6 *eeprom)

{

	eeprom->reg_data_clock = 0;

	eeprom->register_write(eeprom);

	/*

	 * Add a short delay for the pulse to work.

	 * According to the specifications the minimal time

	 * should be 450ns so a 1us delay is sufficient.

	 */

	udelay(1);

}

static void eeprom_93cx6_startup(struct eeprom_93cx6 *eeprom)

{

	/*

	 * Clear all flags, and enable chip select.

	 */

	eeprom->register_read(eeprom);

	eeprom->reg_data_in = 0;

	eeprom->reg_data_out = 0;

	eeprom->reg_data_clock = 0;

	eeprom->reg_chip_select = 1;

	eeprom->register_write(eeprom);

	/*

	 * kick a pulse.

	 */

	eeprom_93cx6_pulse_high(eeprom);

	eeprom_93cx6_pulse_low(eeprom);

}

static void eeprom_93cx6_cleanup(struct eeprom_93cx6 *eeprom)

{

	/*

	 * Clear chip_select and data_in flags.

	 */

	eeprom->register_read(eeprom);

	eeprom->reg_data_in = 0;

	eeprom->reg_chip_select = 0;

	eeprom->register_write(eeprom);

	/*

	 * kick a pulse.

	 */

	eeprom_93cx6_pulse_high(eeprom);

	eeprom_93cx6_pulse_low(eeprom);

}

static void eeprom_93cx6_write_bits(struct eeprom_93cx6 *eeprom,

	const u16 data, const u16 count)

{

	unsigned int i;

	eeprom->register_read(eeprom);

	/*

	 * Clear data flags.

	 */

	eeprom->reg_data_in = 0;

	eeprom->reg_data_out = 0;

	/*

	 * Start writing all bits.

	 */

	for (i = count; i > 0; i--) {

		/*

		 * Check if this bit needs to be set.

		 */

		eeprom->reg_data_in = !!(data & (1 << (i - 1)));

		/*

		 * Write the bit to the eeprom register.

		 */

		eeprom->register_write(eeprom);

		/*

		 * Kick a pulse.

		 */

		eeprom_93cx6_pulse_high(eeprom);

		eeprom_93cx6_pulse_low(eeprom);

	}

	eeprom->reg_data_in = 0;

	eeprom->register_write(eeprom);

}

static void eeprom_93cx6_read_bits(struct eeprom_93cx6 *eeprom,

	u16 *data, const u16 count)

{

	unsigned int i;

	u16 buf = 0;

	eeprom->register_read(eeprom);

	/*

	 * Clear data flags.

	 */

	eeprom->reg_data_in = 0;

	eeprom->reg_data_out = 0;

	/*

	 * Start reading all bits.

	 */

	for (i = count; i > 0; i--) {

		eeprom_93cx6_pulse_high(eeprom);

		eeprom->register_read(eeprom);

		/*

		 * Clear data_in flag.

		 */

		eeprom->reg_data_in = 0;

		/*

		 * Read if the bit has been set.

		 */

		if (eeprom->reg_data_out)

			buf |= (1 << (i - 1));

		eeprom_93cx6_pulse_low(eeprom);

	}

	*data = buf;

}

/**

 * eeprom_93cx6_read - Read multiple words from eeprom

 * @eeprom: Pointer to eeprom structure

 * @word: Word index from where we should start reading

 * @data: target pointer where the information will have to be stored

 *

 * This function will read the eeprom data as host-endian word

 * into the given data pointer.

 */

void eeprom_93cx6_read(struct eeprom_93cx6 *eeprom, const u8 word,

	u16 *data)

{

	u16 command;

	/*

	 * Initialize the eeprom register

	 */

	eeprom_93cx6_startup(eeprom);

	/*

	 * Select the read opcode and the word to be read.

	 */

	command = (PCI_EEPROM_READ_OPCODE << eeprom->width) | word;

	eeprom_93cx6_write_bits(eeprom, command,

		PCI_EEPROM_WIDTH_OPCODE + eeprom->width);

	/*

	 * Read the requested 16 bits.

	 */

	eeprom_93cx6_read_bits(eeprom, data, 16);

	/*

	 * Cleanup eeprom register.

	 */

	eeprom_93cx6_cleanup(eeprom);

}

EXPORT_SYMBOL_GPL(eeprom_93cx6_read);

/**

 * eeprom_93cx6_multiread - Read multiple words from eeprom

 * @eeprom: Pointer to eeprom structure

 * @word: Word index from where we should start reading

 * @data: target pointer where the information will have to be stored

 * @words: Number of words that should be read.

 *

 * This function will read all requested words from the eeprom,

 * this is done by calling eeprom_93cx6_read() multiple times.

 * But with the additional change that while the eeprom_93cx6_read

 * will return host ordered bytes, this method will return little

 * endian words.

 */

void eeprom_93cx6_multiread(struct eeprom_93cx6 *eeprom, const u8 word,

	__le16 *data, const u16 words)

{

	unsigned int i;

	u16 tmp;

	for (i = 0; i < words; i++) {

		tmp = 0;

		eeprom_93cx6_read(eeprom, word + i, &tmp);

		data[i] = cpu_to_le16(tmp);

	}

}

EXPORT_SYMBOL_GPL(eeprom_93cx6_multiread);