Merge branch 'topic/workq-update' into topic/asoc

What:		/sys/bus/rbd/

Date:		November 2010

Contact:	Yehuda Sadeh <yehuda@hq.newdream.net>,

		Sage Weil <sage@newdream.net>

Description:

Being used for adding and removing rbd block devices.

Usage: <mon ip addr> <options> <pool name> <rbd image name> [snap name]

 $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add

The snapshot name can be "-" or omitted to map the image read/write. A <dev-id>

will be assigned for any registered block device. If snapshot is used, it will

be mapped read-only.

Removal of a device:

  $ echo <dev-id> > /sys/bus/rbd/remove

Entries under /sys/bus/rbd/devices/<dev-id>/

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

client_id

	The ceph unique client id that was assigned for this specific session.

major

	The block device major number.

name

	The name of the rbd image.

pool

	The pool where this rbd image resides. The pool-name pair is unique

	per rados system.

size

	The size (in bytes) of the mapped block device.

refresh

	Writing to this file will reread the image header data and set

	all relevant datastructures accordingly.

current_snap

	The current snapshot for which the device is mapped.

create_snap

	Create a snapshot:

	 $ echo <snap-name> > /sys/bus/rbd/devices/<dev-id>/snap_create

rollback_snap

	Rolls back data to the specified snapshot. This goes over the entire

	list of rados blocks and sends a rollback command to each.

	 $ echo <snap-name> > /sys/bus/rbd/devices/<dev-id>/snap_rollback

snap_*

	A directory per each snapshot

Entries under /sys/bus/rbd/devices/<dev-id>/snap_<snap-name>

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

id

	The rados internal snapshot id assigned for this snapshot

size

	The size of the image when this snapshot was taken.

      </sect2>

    </sect1>

  </chapter>

  <chapter id="clk">

    <title>Clock Framework Extensions</title>

!Iinclude/linux/sh_clk.h

  </chapter>

  <chapter id="mach">

    <title>Machine Specific Interfaces</title>

    <sect1 id="dreamcast">

	</orgname>

	<address>

	   <email>hjk@linutronix.de</email>

	   <email>hjk@hansjkoch.de</email>

	</address>

    </affiliation>

</author>

<para>If you know of any translations for this document, or you are

interested in translating it, please email me

<email>hjk@linutronix.de</email>.

<email>hjk@hansjkoch.de</email>.

</para>

</sect1>

<title>Feedback</title>

	<para>Find something wrong with this document? (Or perhaps something

	right?) I would love to hear from you. Please email me at

	<email>hjk@linutronix.de</email>.</para>

	<email>hjk@hansjkoch.de</email>.</para>

</sect1>

</chapter>

   inclusion, it should be accepted by a relevant subsystem maintainer -

   though this acceptance is not a guarantee that the patch will make it

   all the way to the mainline.  The patch will show up in the maintainer's

   subsystem tree and into the staging trees (described below).  When the

   subsystem tree and into the -next trees (described below).  When the

   process works, this step leads to more extensive review of the patch and

   the discovery of any problems resulting from the integration of this

   patch with work being done by others.

normally the right way to go.

2.4: STAGING TREES

2.4: NEXT TREES

The chain of subsystem trees guides the flow of patches into the kernel,

but it also raises an interesting question: what if somebody wants to look

the interesting subsystem trees, but that would be a big and error-prone

job.

The answer comes in the form of staging trees, where subsystem trees are

The answer comes in the form of -next trees, where subsystem trees are

collected for testing and review.  The older of these trees, maintained by

Andrew Morton, is called "-mm" (for memory management, which is how it got

started).  The -mm tree integrates patches from a long list of subsystem

Use of the MMOTM tree is likely to be a frustrating experience, though;

there is a definite chance that it will not even compile.

The other staging tree, started more recently, is linux-next, maintained by

The other -next tree, started more recently, is linux-next, maintained by

Stephen Rothwell.  The linux-next tree is, by design, a snapshot of what

the mainline is expected to look like after the next merge window closes.

Linux-next trees are announced on the linux-kernel and linux-next mailing

See http://lwn.net/Articles/289013/ for more information on this topic, and

stay tuned; much is still in flux where linux-next is involved.

Besides the mmotm and linux-next trees, the kernel source tree now contains

the drivers/staging/ directory and many sub-directories for drivers or

filesystems that are on their way to being added to the kernel tree

proper, but they remain in drivers/staging/ while they still need more

work.

2.4.1: STAGING TREES

The kernel source tree now contains the drivers/staging/ directory, where

many sub-directories for drivers or filesystems that are on their way to

being added to the kernel tree live.  They remain in drivers/staging while

they still need more work; once complete, they can be moved into the

kernel proper.  This is a way to keep track of drivers that aren't

up to Linux kernel coding or quality standards, but people may want to use

them and track development.

Greg Kroah-Hartman currently (as of 2.6.36) maintains the staging tree.

Drivers that still need work are sent to him, with each driver having

its own subdirectory in drivers/staging/.  Along with the driver source

files, a TODO file should be present in the directory as well.  The TODO

file lists the pending work that the driver needs for acceptance into

the kernel proper, as well as a list of people that should be Cc'd for any

patches to the driver.  Staging drivers that don't currently build should

have their config entries depend upon CONFIG_BROKEN.  Once they can

be successfully built without outside patches, CONFIG_BROKEN can be removed.

2.5: TOOLS

Device Interfaces

Introduction

~~~~~~~~~~~~

Device interfaces are the logical interfaces of device classes that correlate

directly to userspace interfaces, like device nodes. 

Each device class may have multiple interfaces through which you can 

access the same device. An input device may support the mouse interface, 

the 'evdev' interface, and the touchscreen interface. A SCSI disk would 

support the disk interface, the SCSI generic interface, and possibly a raw 

device interface. 

Device interfaces are registered with the class they belong to. As devices

are added to the class, they are added to each interface registered with

the class. The interface is responsible for determining whether the device

supports the interface or not. 

Programming Interface

~~~~~~~~~~~~~~~~~~~~~

struct device_interface {

	char			* name;

	rwlock_t		lock;

	u32			devnum;

	struct device_class	* devclass;

	struct list_head	node;

	struct driver_dir_entry	dir;

	int (*add_device)(struct device *);

	int (*add_device)(struct intf_data *);

};

int interface_register(struct device_interface *);

void interface_unregister(struct device_interface *);

An interface must specify the device class it belongs to. It is added

to that class's list of interfaces on registration.

Interfaces can be added to a device class at any time. Whenever it is

added, each device in the class is passed to the interface's

add_device callback. When an interface is removed, each device is

removed from the interface.

Devices

~~~~~~~

Once a device is added to a device class, it is added to each

interface that is registered with the device class. The class

is expected to place a class-specific data structure in 

struct device::class_data. The interface can use that (along with

other fields of struct device) to determine whether or not the driver

and/or device support that particular interface.

Data

~~~~

struct intf_data {

	struct list_head	node;

	struct device_interface	* intf;

	struct device 		* dev;

	u32			intf_num;

};

int interface_add_data(struct interface_data *);

The interface is responsible for allocating and initializing a struct 

intf_data and calling interface_add_data() to add it to the device's list

of interfaces it belongs to. This list will be iterated over when the device

is removed from the class (instead of all possible interfaces for a class).

This structure should probably be embedded in whatever per-device data 

structure the interface is allocating anyway.

Devices are enumerated within the interface. This happens in interface_add_data()

and the enumerated value is stored in the struct intf_data for that device. 

sysfs

~~~~~

Each interface is given a directory in the directory of the device

class it belongs to:

Interfaces get a directory in the class's directory as well:

   class/

   `-- input

       |-- devices

       |-- drivers

       |-- mouse

       `-- evdev

When a device is added to the interface, a symlink is created that points 

to the device's directory in the physical hierarchy:

   class/

   `-- input

       |-- devices

       |   `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/

       |-- drivers

       |   `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/

       |-- mouse

       |   `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/

       `-- evdev

           `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/

Future Plans

~~~~~~~~~~~~

A device interface is correlated directly with a userspace interface

for a device, specifically a device node. For instance, a SCSI disk

exposes at least two interfaces to userspace: the standard SCSI disk

interface and the SCSI generic interface. It might also export a raw

device interface. 

Many interfaces have a major number associated with them and each

device gets a minor number. Or, multiple interfaces might share one

major number, and each will receive a range of minor numbers (like in

the case of input devices).

These major and minor numbers could be stored in the interface

structure. Major and minor allocations could happen when the interface

is registered with the class, or via a helper function.