Merge branch 'regulator-drivers' into regulator-next

What:           /sys/block/rssd*/registers

Date:           March 2012

KernelVersion:  3.3

Contact:        Asai Thambi S P <asamymuthupa@micron.com>

Description:    This is a read-only file. Dumps below driver information and

                hardware registers.

                    - S ACTive

                    - Command Issue

                    - Completed

                    - PORT IRQ STAT

                    - HOST IRQ STAT

                    - Allocated

                    - Commands in Q

What:           /sys/block/rssd*/status

Date:           April 2012

KernelVersion:  3.4

Contact:        Asai Thambi S P <asamymuthupa@micron.com>

Description:    This is a read-only file. Indicates the status of the device.

What:           /sys/block/rssd*/flags

Date:           May 2012

KernelVersion:  3.5

Contact:        Asai Thambi S P <asamymuthupa@micron.com>

Description:    This is a read-only file. Dumps the flags in port and driver

                data structure

Contact:	linux-mtd@lists.infradead.org

Description:

		This allows the user to examine and adjust the criteria by which

		mtd returns -EUCLEAN from mtd_read().  If the maximum number of

		bit errors that were corrected on any single region comprising

		an ecc step (as reported by the driver) equals or exceeds this

		value, -EUCLEAN is returned.  Otherwise, absent an error, 0 is

		returned.  Higher layers (e.g., UBI) use this return code as an

		indication that an erase block may be degrading and should be

		scrutinized as a candidate for being marked as bad.

		mtd returns -EUCLEAN from mtd_read() and mtd_read_oob().  If the

		maximum number of bit errors that were corrected on any single

		region comprising an ecc step (as reported by the driver) equals

		or exceeds this value, -EUCLEAN is returned.  Otherwise, absent

		an error, 0 is returned.  Higher layers (e.g., UBI) use this

		return code as an indication that an erase block may be

		degrading and should be scrutinized as a candidate for being

		marked as bad.

		The initial value may be specified by the flash device driver.

		If not, then the default value is ecc_strength.

		block degradation, but high enough to avoid the consequences of

		a persistent return value of -EUCLEAN on devices where sticky

		bitflips occur.  Note that if bitflip_threshold exceeds

		ecc_strength, -EUCLEAN is never returned by mtd_read().

		ecc_strength, -EUCLEAN is never returned by the read operations.

		Conversely, if bitflip_threshold is zero, -EUCLEAN is always

		returned, absent a hard error.

	    from RGB to Y'CbCr color space.

	    </entry>

	  </row>

	  <row id = "v4l2-jpeg-chroma-subsampling">

	  <row>

	    <entrytbl spanname="descr" cols="2">

	      <tbody valign="top">

		<row>

	    processing controls. These controls are described in <xref

	    linkend="image-process-controls" />.</entry>

	  </row>

	  <row>

	    <entry><constant>V4L2_CTRL_CLASS_JPEG</constant></entry>

	    <entry>0x9d0000</entry>

	    <entry>The class containing JPEG compression controls.

These controls are described in <xref

		linkend="jpeg-controls" />.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>

Construction Parameters

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

    <version> <dev> <hash_dev> <hash_start>

    <version> <dev> <hash_dev>

    <data_block_size> <hash_block_size>

    <num_data_blocks> <hash_start_block>

    <algorithm> <digest> <salt>

<version>

    This is the version number of the on-disk format.

    This is the type of the on-disk hash format.

    0 is the original format used in the Chromium OS.

      The salt is appended when hashing, digests are stored continuously and

      padded with zeros to the power of two.

<dev>

    This is the device containing the data the integrity of which needs to be

    This is the device containing data, the integrity of which needs to be

    checked.  It may be specified as a path, like /dev/sdaX, or a device number,

    <major>:<minor>.

<hash_dev>

    This is the device that that supplies the hash tree data.  It may be

    This is the device that supplies the hash tree data.  It may be

    specified similarly to the device path and may be the same device.  If the

    same device is used, the hash_start should be outside of the dm-verity

    configured device size.

    same device is used, the hash_start should be outside the configured

    dm-verity device.

<data_block_size>

    The block size on a data device.  Each block corresponds to one digest on

    the hash device.

    The block size on a data device in bytes.

    Each block corresponds to one digest on the hash device.

<hash_block_size>

    The size of a hash block.

    The size of a hash block in bytes.

<num_data_blocks>

    The number of data blocks on the data device.  Additional blocks are

has been authenticated in some way (cryptographic signatures, etc).

After instantiation, all hashes will be verified on-demand during

disk access.  If they cannot be verified up to the root node of the

tree, the root hash, then the I/O will fail.  This should identify

tree, the root hash, then the I/O will fail.  This should detect

tampering with any data on the device and the hash data.

Cryptographic hashes are used to assert the integrity of the device on a

per-block basis. This allows for a lightweight hash computation on first read

into the page cache.  Block hashes are stored linearly-aligned to the nearest

block the size of a page.

into the page cache. Block hashes are stored linearly, aligned to the nearest

block size.

Hash Tree

---------

Each node in the tree is a cryptographic hash.  If it is a leaf node, the hash

is of some block data on disk.  If it is an intermediary node, then the hash is

of a number of child nodes.

of some data block on disk is calculated. If it is an intermediary node,

the hash of a number of child nodes is calculated.

Each entry in the tree is a collection of neighboring nodes that fit in one

block.  The number is determined based on block_size and the size of the

On-disk format

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

Below is the recommended on-disk format. The verity kernel code does not

read the on-disk header. It only reads the hash blocks which directly

follow the header. It is expected that a user-space tool will verify the

integrity of the verity_header and then call dmsetup with the correct

parameters. Alternatively, the header can be omitted and the dmsetup

parameters can be passed via the kernel command-line in a rooted chain

of trust where the command-line is verified.

The verity kernel code does not read the verity metadata on-disk header.

It only reads the hash blocks which directly follow the header.

It is expected that a user-space tool will verify the integrity of the

verity header.

The on-disk format is especially useful in cases where the hash blocks

are on a separate partition. The magic number allows easy identification

of the partition contents. Alternatively, the hash blocks can be stored

in the same partition as the data to be verified. In such a configuration

the filesystem on the partition would be sized a little smaller than

the full-partition, leaving room for the hash blocks.

struct superblock {

	uint8_t signature[8]

		"verity\0\0";

	uint8_t version;

		1 - current format

	uint8_t data_block_bits;

		log2(data block size)

	uint8_t hash_block_bits;

		log2(hash block size)

	uint8_t pad1[1];

		zero padding

	uint16_t salt_size;

		big-endian salt size

	uint8_t pad2[2];

		zero padding

	uint32_t data_blocks_hi;

		big-endian high 32 bits of the 64-bit number of data blocks

	uint32_t data_blocks_lo;

		big-endian low 32 bits of the 64-bit number of data blocks

	uint8_t algorithm[16];

		cryptographic algorithm

	uint8_t salt[384];

		salt (the salt size is specified above)

	uint8_t pad3[88];

		zero padding to 512-byte boundary

}

Alternatively, the header can be omitted and the dmsetup parameters can

be passed via the kernel command-line in a rooted chain of trust where

the command-line is verified.

Directly following the header (and with sector number padded to the next hash

block boundary) are the hash blocks which are stored a depth at a time

(starting from the root), sorted in order of increasing index.

The full specification of kernel parameters and on-disk metadata format

is available at the cryptsetup project's wiki page

  http://code.google.com/p/cryptsetup/wiki/DMVerity

Status

======

V (for Valid) is returned if every check performed so far was valid.

Example

=======

Set up a device:

  dmsetup create vroot --table \

    "0 2097152 "\

    "verity 1 /dev/sda1 /dev/sda2 4096 4096 2097152 1 "\

  # dmsetup create vroot --readonly --table \

    "0 2097152 verity 1 /dev/sda1 /dev/sda2 4096 4096 262144 1 sha256 "\

    "4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\

    "1234000000000000000000000000000000000000000000000000000000000000"

A command line tool veritysetup is available to compute or verify

the hash tree or activate the kernel driver.  This is available from

the LVM2 upstream repository and may be supplied as a package called

device-mapper-verity-tools:

    git://sources.redhat.com/git/lvm2

    http://sourceware.org/git/?p=lvm2.git

    http://sourceware.org/cgi-bin/cvsweb.cgi/LVM2/verity?cvsroot=lvm2

veritysetup -a vroot /dev/sda1 /dev/sda2 \

the hash tree or activate the kernel device. This is available from

the cryptsetup upstream repository http://code.google.com/p/cryptsetup/

(as a libcryptsetup extension).

Create hash on the device:

  # veritysetup format /dev/sda1 /dev/sda2

  ...

  Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076

Activate the device:

  # veritysetup create vroot /dev/sda1 /dev/sda2 \

    4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076