Merge branch 'linus' into perfcounters/rename

The OMAP PM interface

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

This document describes the temporary OMAP PM interface.  Driver

authors use these functions to communicate minimum latency or

throughput constraints to the kernel power management code.

Over time, the intention is to merge features from the OMAP PM

interface into the Linux PM QoS code.

Drivers need to express PM parameters which:

- support the range of power management parameters present in the TI SRF;

- separate the drivers from the underlying PM parameter

  implementation, whether it is the TI SRF or Linux PM QoS or Linux

  latency framework or something else;

- specify PM parameters in terms of fundamental units, such as

  latency and throughput, rather than units which are specific to OMAP

  or to particular OMAP variants;

- allow drivers which are shared with other architectures (e.g.,

  DaVinci) to add these constraints in a way which won't affect non-OMAP

  systems,

- can be implemented immediately with minimal disruption of other

  architectures.

This document proposes the OMAP PM interface, including the following

five power management functions for driver code:

1. Set the maximum MPU wakeup latency:

   (*pdata->set_max_mpu_wakeup_lat)(struct device *dev, unsigned long t)

2. Set the maximum device wakeup latency:

   (*pdata->set_max_dev_wakeup_lat)(struct device *dev, unsigned long t)

3. Set the maximum system DMA transfer start latency (CORE pwrdm):

   (*pdata->set_max_sdma_lat)(struct device *dev, long t)

4. Set the minimum bus throughput needed by a device:

   (*pdata->set_min_bus_tput)(struct device *dev, u8 agent_id, unsigned long r)

5. Return the number of times the device has lost context

   (*pdata->get_dev_context_loss_count)(struct device *dev)

Further documentation for all OMAP PM interface functions can be

found in arch/arm/plat-omap/include/mach/omap-pm.h.

The OMAP PM layer is intended to be temporary

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

The intention is that eventually the Linux PM QoS layer should support

the range of power management features present in OMAP3.  As this

happens, existing drivers using the OMAP PM interface can be modified

to use the Linux PM QoS code; and the OMAP PM interface can disappear.

Driver usage of the OMAP PM functions

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

As the 'pdata' in the above examples indicates, these functions are

exposed to drivers through function pointers in driver .platform_data

structures.  The function pointers are initialized by the board-*.c

files to point to the corresponding OMAP PM functions:

.set_max_dev_wakeup_lat will point to

omap_pm_set_max_dev_wakeup_lat(), etc.  Other architectures which do

not support these functions should leave these function pointers set

to NULL.  Drivers should use the following idiom:

        if (pdata->set_max_dev_wakeup_lat)

            (*pdata->set_max_dev_wakeup_lat)(dev, t);

The most common usage of these functions will probably be to specify

the maximum time from when an interrupt occurs, to when the device

becomes accessible.  To accomplish this, driver writers should use the

set_max_mpu_wakeup_lat() function to to constrain the MPU wakeup

latency, and the set_max_dev_wakeup_lat() function to constrain the

device wakeup latency (from clk_enable() to accessibility).  For

example,

        /* Limit MPU wakeup latency */

        if (pdata->set_max_mpu_wakeup_lat)

            (*pdata->set_max_mpu_wakeup_lat)(dev, tc);

        /* Limit device powerdomain wakeup latency */

        if (pdata->set_max_dev_wakeup_lat)

            (*pdata->set_max_dev_wakeup_lat)(dev, td);

        /* total wakeup latency in this example: (tc + td) */

The PM parameters can be overwritten by calling the function again

with the new value.  The settings can be removed by calling the

function with a t argument of -1 (except in the case of

set_max_bus_tput(), which should be called with an r argument of 0).

The fifth function above, omap_pm_get_dev_context_loss_count(),

is intended as an optimization to allow drivers to determine whether the

device has lost its internal context.  If context has been lost, the

driver must restore its internal context before proceeding.

Other specialized interface functions

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

The five functions listed above are intended to be usable by any

device driver.  DSPBridge and CPUFreq have a few special requirements.

DSPBridge expresses target DSP performance levels in terms of OPP IDs.

CPUFreq expresses target MPU performance levels in terms of MPU

frequency.  The OMAP PM interface contains functions for these

specialized cases to convert that input information (OPPs/MPU

frequency) into the form that the underlying power management

implementation needs:

6. (*pdata->dsp_get_opp_table)(void)

7. (*pdata->dsp_set_min_opp)(u8 opp_id)

8. (*pdata->dsp_get_opp)(void)

9. (*pdata->cpu_get_freq_table)(void)

10. (*pdata->cpu_set_freq)(unsigned long f)

11. (*pdata->cpu_get_freq)(void)

				work on some specific architectures or

				work on some specific architectures or

				processors.

				processors.

cpuinfo_cur_freq :		Current speed of the CPU, in KHz.

cpuinfo_cur_freq :		Current frequency of the CPU as obtained from

				the hardware, in KHz. This is the frequency

				the CPU actually runs at.

scaling_available_frequencies : List of available frequencies, in KHz.

scaling_available_frequencies : List of available frequencies, in KHz.

scaling_driver :		Hardware driver for cpufreq.

scaling_driver :		Hardware driver for cpufreq.

scaling_cur_freq :		Current frequency of the CPU, in KHz.

scaling_cur_freq :		Current frequency of the CPU as determined by

				the governor and cpufreq core, in KHz. This is

				the frequency the kernel thinks the CPU runs

				at.

If you have selected the "userspace" governor which allows you to

If you have selected the "userspace" governor which allows you to

set the CPU operating frequency to a specific value, you can read out

set the CPU operating frequency to a specific value, you can read out

                     	mount options "ro,noload" can be used to prevent

                     	mount options "ro,noload" can be used to prevent

		     	writes to the filesystem.

		     	writes to the filesystem.

journal_checksum	Enable checksumming of the journal transactions.

			This will allow the recovery code in e2fsck and the

			kernel to detect corruption in the kernel.  It is a

			compatible change and will be ignored by older kernels.

journal_async_commit	Commit block can be written to disk without waiting

journal_async_commit	Commit block can be written to disk without waiting

			for descriptor blocks. If enabled older kernels cannot

			for descriptor blocks. If enabled older kernels cannot

			mount the device. This will enable 'journal_checksum'

			mount the device.

			internally.

journal=update		Update the ext4 file system's journal to the current

journal=update		Update the ext4 file system's journal to the current

			format.

			format.

sb=n			Use alternate superblock at this location.

sb=n			Use alternate superblock at this location.

quota

quota			These options are ignored by the filesystem. They

noquota

noquota			are used only by quota tools to recognize volumes

grpquota

grpquota		where quota should be turned on. See documentation

usrquota

usrquota		in the quota-tools package for more details

			(http://sourceforge.net/projects/linuxquota).

jqfmt=<quota type>	These options tell filesystem details about quota

usrjquota=<file>	so that quota information can be properly updated

grpjquota=<file>	during journal replay. They replace the above

			quota options. See documentation in the quota-tools

			package for more details

			(http://sourceforge.net/projects/linuxquota).

bh		(*)	ext4 associates buffer heads to data pages to

bh		(*)	ext4 associates buffer heads to data pages to

nobh			(a) cache disk block mapping information

nobh			(a) cache disk block mapping information

Kernel driver wm831x-hwmon

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

Supported chips:

  * Wolfson Microelectronics WM831x PMICs

    Prefix: 'wm831x'

    Datasheet:

	http://www.wolfsonmicro.com/products/WM8310

	http://www.wolfsonmicro.com/products/WM8311

	http://www.wolfsonmicro.com/products/WM8312

Authors: Mark Brown <broonie@opensource.wolfsonmicro.com>

Description

-----------

The WM831x series of PMICs include an AUXADC which can be used to

monitor a range of system operating parameters, including the voltages

of the major supplies within the system.  Currently the driver provides

reporting of all the input values but does not provide any alarms.

Voltage Monitoring

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

Voltages are sampled by a 12 bit ADC.  Voltages in milivolts are 1.465

times the ADC value.

Temperature Monitoring

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

Temperatures are sampled by a 12 bit ADC.  Chip and battery temperatures

are available.  The chip temperature is calculated as:

	Degrees celsius = (512.18 - data) / 1.0983

while the battery temperature calculation will depend on the NTC

thermistor component.

Kernel driver wm8350-hwmon

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

Supported chips:

  * Wolfson Microelectronics WM835x PMICs

    Prefix: 'wm8350'

    Datasheet:

	http://www.wolfsonmicro.com/products/WM8350

	http://www.wolfsonmicro.com/products/WM8351

	http://www.wolfsonmicro.com/products/WM8352

Authors: Mark Brown <broonie@opensource.wolfsonmicro.com>

Description

-----------

The WM835x series of PMICs include an AUXADC which can be used to

monitor a range of system operating parameters, including the voltages

of the major supplies within the system.  Currently the driver provides

simple access to these major supplies.

Voltage Monitoring

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

Voltages are sampled by a 12 bit ADC.  For the internal supplies the ADC

is referenced to the system VRTC.