Merge branch 'master' of master.kernel.org:/pub/scm/linux/kernel/git/davem/net-2.6

		match the driver to the device.  For example:

		# echo "046d c315" > /sys/bus/usb/drivers/foo/remove_id

What:		/sys/bus/usb/device/.../avoid_reset

What:		/sys/bus/usb/device/.../avoid_reset_quirk

Date:		December 2009

Contact:	Oliver Neukum <oliver@neukum.org>

Description:

Ceph Distributed File System

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

Ceph is a distributed network file system designed to provide good

performance, reliability, and scalability.

Basic features include:

 * POSIX semantics

 * Seamless scaling from 1 to many thousands of nodes

 * High availability and reliability.  No single points of failure.

 * N-way replication of data across storage nodes

 * Fast recovery from node failures

 * Automatic rebalancing of data on node addition/removal

 * Easy deployment: most FS components are userspace daemons

Also,

 * Flexible snapshots (on any directory)

 * Recursive accounting (nested files, directories, bytes)

In contrast to cluster filesystems like GFS, OCFS2, and GPFS that rely

on symmetric access by all clients to shared block devices, Ceph

separates data and metadata management into independent server

clusters, similar to Lustre.  Unlike Lustre, however, metadata and

storage nodes run entirely as user space daemons.  Storage nodes

utilize btrfs to store data objects, leveraging its advanced features

(checksumming, metadata replication, etc.).  File data is striped

across storage nodes in large chunks to distribute workload and

facilitate high throughputs.  When storage nodes fail, data is

re-replicated in a distributed fashion by the storage nodes themselves

(with some minimal coordination from a cluster monitor), making the

system extremely efficient and scalable.

Metadata servers effectively form a large, consistent, distributed

in-memory cache above the file namespace that is extremely scalable,

dynamically redistributes metadata in response to workload changes,

and can tolerate arbitrary (well, non-Byzantine) node failures.  The

metadata server takes a somewhat unconventional approach to metadata

storage to significantly improve performance for common workloads.  In

particular, inodes with only a single link are embedded in

directories, allowing entire directories of dentries and inodes to be

loaded into its cache with a single I/O operation.  The contents of

extremely large directories can be fragmented and managed by

independent metadata servers, allowing scalable concurrent access.

The system offers automatic data rebalancing/migration when scaling

from a small cluster of just a few nodes to many hundreds, without

requiring an administrator carve the data set into static volumes or

go through the tedious process of migrating data between servers.

When the file system approaches full, new nodes can be easily added

and things will "just work."

Ceph includes flexible snapshot mechanism that allows a user to create

a snapshot on any subdirectory (and its nested contents) in the

system.  Snapshot creation and deletion are as simple as 'mkdir

.snap/foo' and 'rmdir .snap/foo'.

Ceph also provides some recursive accounting on directories for nested

files and bytes.  That is, a 'getfattr -d foo' on any directory in the

system will reveal the total number of nested regular files and

subdirectories, and a summation of all nested file sizes.  This makes

the identification of large disk space consumers relatively quick, as

no 'du' or similar recursive scan of the file system is required.

Mount Syntax

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

The basic mount syntax is:

 # mount -t ceph monip[:port][,monip2[:port]...]:/[subdir] mnt

You only need to specify a single monitor, as the client will get the

full list when it connects.  (However, if the monitor you specify

happens to be down, the mount won't succeed.)  The port can be left

off if the monitor is using the default.  So if the monitor is at

1.2.3.4,

 # mount -t ceph 1.2.3.4:/ /mnt/ceph

is sufficient.  If /sbin/mount.ceph is installed, a hostname can be

used instead of an IP address.

Mount Options

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

  ip=A.B.C.D[:N]

	Specify the IP and/or port the client should bind to locally.

	There is normally not much reason to do this.  If the IP is not

	specified, the client's IP address is determined by looking at the

	address it's connection to the monitor originates from.

  wsize=X

	Specify the maximum write size in bytes.  By default there is no

	maximu.  Ceph will normally size writes based on the file stripe

	size.

  rsize=X

	Specify the maximum readahead.

  mount_timeout=X

	Specify the timeout value for mount (in seconds), in the case

	of a non-responsive Ceph file system.  The default is 30

	seconds.

  rbytes

	When stat() is called on a directory, set st_size to 'rbytes',

	the summation of file sizes over all files nested beneath that

	directory.  This is the default.

  norbytes

	When stat() is called on a directory, set st_size to the

	number of entries in that directory.

  nocrc

	Disable CRC32C calculation for data writes.  If set, the OSD

	must rely on TCP's error correction to detect data corruption

	in the data payload.

  noasyncreaddir

	Disable client's use its local cache to satisfy	readdir

	requests.  (This does not change correctness; the client uses

	cached metadata only when a lease or capability ensures it is

	valid.)

More Information

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

For more information on Ceph, see the home page at

	http://ceph.newdream.net/

The Linux kernel client source tree is available at

	git://ceph.newdream.net/linux-ceph-client.git

and the source for the full system is at

	git://ceph.newdream.net/ceph.git

0x92	00-0F	drivers/usb/mon/mon_bin.c

0x93	60-7F	linux/auto_fs.h

0x94	all	fs/btrfs/ioctl.h

0x97	00-7F	fs/ceph/ioctl.h		Ceph file system

0x99	00-0F				537-Addinboard driver

					<mailto:buk@buks.ipn.de>

0xA0	all	linux/sdp/sdp.h		Industrial Device Project

direct expression of inheritance, so other techniques - such as structure

embedding - must be used.

So, for example, the UIO code has a structure that defines the memory

region associated with a uio device:

(As an aside, for those familiar with the kernel linked list implementation,

this is analogous as to how "list_head" structs are rarely useful on

their own, but are invariably found embedded in the larger objects of

interest.)

struct uio_mem {

So, for example, the UIO code in drivers/uio/uio.c has a structure that

defines the memory region associated with a uio device:

    struct uio_map {

	struct kobject kobj;

	unsigned long addr;

	unsigned long size;

	int memtype;

	void __iomem *internal_addr;

	struct uio_mem *mem;

    };

If you have a struct uio_mem structure, finding its embedded kobject is

If you have a struct uio_map structure, finding its embedded kobject is

just a matter of using the kobj member.  Code that works with kobjects will

often have the opposite problem, however: given a struct kobject pointer,

what is the pointer to the containing structure?  You must avoid tricks

    container_of(pointer, type, member)

where pointer is the pointer to the embedded kobject, type is the type of

the containing structure, and member is the name of the structure field to

which pointer points.  The return value from container_of() is a pointer to

the given type. So, for example, a pointer "kp" to a struct kobject

embedded within a struct uio_mem could be converted to a pointer to the

containing uio_mem structure with:

where:

  * "pointer" is the pointer to the embedded kobject,

  * "type" is the type of the containing structure, and

  * "member" is the name of the structure field to which "pointer" points.

The return value from container_of() is a pointer to the corresponding

container type. So, for example, a pointer "kp" to a struct kobject

embedded *within* a struct uio_map could be converted to a pointer to the

*containing* uio_map structure with:

    struct uio_map *u_map = container_of(kp, struct uio_map, kobj);

For convenience, programmers often define a simple macro for "back-casting"

kobject pointers to the containing type.  Exactly this happens in the

earlier drivers/uio/uio.c, as you can see here:

    struct uio_map {

        struct kobject kobj;

        struct uio_mem *mem;

    };

    #define to_map(map) container_of(map, struct uio_map, kobj)

    struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj);

where the macro argument "map" is a pointer to the struct kobject in

question.  That macro is subsequently invoked with:

Programmers often define a simple macro for "back-casting" kobject pointers

to the containing type.

    struct uio_map *map = to_map(kobj);

Initialization of kobjects

Example code to copy from

For a more complete example of using ksets and kobjects properly, see the

sample/kobject/kset-example.c code.

example programs samples/kobject/{kobject-example.c,kset-example.c},

which will be built as loadable modules if you select CONFIG_SAMPLE_KOBJECT.

       STMicroelectronics 10/100/1000 Synopsys Ethernet driver

Copyright (C) 2007-2010  STMicroelectronics Ltd

Author: Giuseppe Cavallaro <peppe.cavallaro@st.com>

This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers

(Synopsys IP blocks); it has been fully tested on STLinux platforms.

Currently this network device driver is for all STM embedded MAC/GMAC

(7xxx SoCs).

DWC Ether MAC 10/100/1000 Universal version 3.41a and DWC Ether MAC 10/100

Universal version 4.0 have been used for developing the first code

implementation.

Please, for more information also visit: www.stlinux.com

1) Kernel Configuration

The kernel configuration option is STMMAC_ETH:

 Device Drivers ---> Network device support ---> Ethernet (1000 Mbit) --->

 STMicroelectronics 10/100/1000 Ethernet driver (STMMAC_ETH)

2) Driver parameters list:

	debug: message level (0: no output, 16: all);

	phyaddr: to manually provide the physical address to the PHY device;

	dma_rxsize: DMA rx ring size;

	dma_txsize: DMA tx ring size;

	buf_sz: DMA buffer size;

	tc: control the HW FIFO threshold;

	tx_coe: Enable/Disable Tx Checksum Offload engine;

	watchdog: transmit timeout (in milliseconds);

	flow_ctrl: Flow control ability [on/off];

	pause: Flow Control Pause Time;

	tmrate: timer period (only if timer optimisation is configured).

3) Command line options

Driver parameters can be also passed in command line by using:

	stmmaceth=dma_rxsize:128,dma_txsize:512

4) Driver information and notes

4.1) Transmit process

The xmit method is invoked when the kernel needs to transmit a packet; it sets

the descriptors in the ring and informs the DMA engine that there is a packet

ready to be transmitted.

Once the controller has finished transmitting the packet, an interrupt is

triggered; So the driver will be able to release the socket buffers.

By default, the driver sets the NETIF_F_SG bit in the features field of the

net_device structure enabling the scatter/gather feature.

4.2) Receive process

When one or more packets are received, an interrupt happens. The interrupts

are not queued so the driver has to scan all the descriptors in the ring during

the receive process.

This is based on NAPI so the interrupt handler signals only if there is work to be

done, and it exits.

Then the poll method will be scheduled at some future point.

The incoming packets are stored, by the DMA, in a list of pre-allocated socket

buffers in order to avoid the memcpy (Zero-copy).

4.3) Timer-Driver Interrupt

Instead of having the device that asynchronously notifies the frame receptions, the

driver configures a timer to generate an interrupt at regular intervals.

Based on the granularity of the timer, the frames that are received by the device

will experience different levels of latency. Some NICs have dedicated timer

device to perform this task. STMMAC can use either the RTC device or the TMU

channel 2  on STLinux platforms.

The timers frequency can be passed to the driver as parameter; when change it,

take care of both hardware capability and network stability/performance impact.

Several performance tests on STM platforms showed this optimisation allows to spare

the CPU while having the maximum throughput.

4.4) WOL

Wake up on Lan feature through Magic Frame is only supported for the GMAC

core.

4.5) DMA descriptors

Driver handles both normal and enhanced descriptors. The latter has been only

tested on DWC Ether MAC 10/100/1000 Universal version 3.41a.

4.6) Ethtool support

Ethtool is supported. Driver statistics and internal errors can be taken using:

ethtool -S ethX command. It is possible to dump registers etc.

4.7) Jumbo and Segmentation Offloading

Jumbo frames are supported and tested for the GMAC.

The GSO has been also added but it's performed in software.

LRO is not supported.

4.8) Physical

The driver is compatible with PAL to work with PHY and GPHY devices.

4.9) Platform information

Several information came from the platform; please refer to the

driver's Header file in include/linux directory.

struct plat_stmmacenet_data {

        int bus_id;

        int pbl;

        int has_gmac;

        void (*fix_mac_speed)(void *priv, unsigned int speed);

        void (*bus_setup)(unsigned long ioaddr);

#ifdef CONFIG_STM_DRIVERS

        struct stm_pad_config *pad_config;

#endif

        void *bsp_priv;

};

Where:

- pbl (Programmable Burst Length) is maximum number of

  beats to be transferred in one DMA transaction.

  GMAC also enables the 4xPBL by default.

- fix_mac_speed and bus_setup are used to configure internal target

  registers (on STM platforms);

- has_gmac: GMAC core is on board (get it at run-time in the next step);

- bus_id: bus identifier.

struct plat_stmmacphy_data {

        int bus_id;

        int phy_addr;

        unsigned int phy_mask;

        int interface;

        int (*phy_reset)(void *priv);

        void *priv;

};

Where:

- bus_id: bus identifier;

- phy_addr: physical address used for the attached phy device;

            set it to -1 to get it at run-time;

- interface: physical MII interface mode;

- phy_reset: hook to reset HW function.

TODO:

- Continue to make the driver more generic and suitable for other Synopsys

  Ethernet controllers used on other architectures (i.e. ARM).

- 10G controllers are not supported.

- MAC uses Normal descriptors and GMAC uses enhanced ones.

  This is a limit that should be reviewed. MAC could want to

  use the enhanced structure.

- Checksumming: Rx/Tx csum is done in HW in case of GMAC only.

- Review the timer optimisation code to use an embedded device that seems to be

  available in new chip generations.