Merge remote-tracking branch 'origin' into spi/next

	- info on the magic SysRq key.

telephony/

	- directory with info on telephony (e.g. voice over IP) support.

time_interpolators.txt

	- info on time interpolators.

uml/

	- directory with information about User Mode Linux.

unicode.txt

	- directory with info on the Linux vm code.

volatile-considered-harmful.txt

	- Why the "volatile" type class should not be used

voyager.txt

	- guide to running Linux on the Voyager architecture.

w1/

	- directory with documents regarding the 1-wire (w1) subsystem.

watchdog/

What:		/sys/firmware/efi/vars

Date:		April 2004

Contact:	Matt Domsch <Matt_Domsch@dell.com>

Description:

		This directory exposes interfaces for interactive with

		EFI variables.  For more information on EFI variables,

		see 'Variable Services' in the UEFI specification

		(section 7.2 in specification version 2.3 Errata D).

		In summary, EFI variables are named, and are classified

		into separate namespaces through the use of a vendor

		GUID.  They also have an arbitrary binary value

		associated with them.

		The efivars module enumerates these variables and

		creates a separate directory for each one found.  Each

		directory has a name of the form "<key>-<vendor guid>"

		and contains the following files:

		attributes:	A read-only text file enumerating the

				EFI variable flags.  Potential values

				include:

				EFI_VARIABLE_NON_VOLATILE

				EFI_VARIABLE_BOOTSERVICE_ACCESS

				EFI_VARIABLE_RUNTIME_ACCESS

				EFI_VARIABLE_HARDWARE_ERROR_RECORD

				EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS

				See the EFI documentation for an

				explanation of each of these variables.

		data:		A read-only binary file that can be read

				to attain the value of the EFI variable

		guid:		The vendor GUID of the variable.  This

				should always match the GUID in the

				variable's name.

		raw_var:	A binary file that can be read to obtain

				a structure that contains everything

				there is to know about the variable.

				For structure definition see "struct

				efi_variable" in the kernel sources.

				This file can also be written to in

				order to update the value of a variable.

				For this to work however, all fields of

				the "struct efi_variable" passed must

				match byte for byte with the structure

				read out of the file, save for the value

				portion.

				**Note** the efi_variable structure

				read/written with this file contains a

				'long' type that may change widths

				depending on your underlying

				architecture.

		size:		As ASCII representation of the size of

				the variable's value.

		In addition, two other magic binary files are provided

		in the top-level directory and are used for adding and

		removing variables:

		new_var:	Takes a "struct efi_variable" and

				instructs the EFI firmware to create a

				new variable.

		del_var:	Takes a "struct efi_variable" and

				instructs the EFI firmware to remove any

				variable that has a matching vendor GUID

				and variable key name.

Where:		/dev/pstore/...

Date:		January 2011

Kernel Version: 2.6.38

Contact:	tony.luck@intel.com

Description:	Generic interface to platform dependent persistent storage.

		Platforms that provide a mechanism to preserve some data

		across system reboots can register with this driver to

		provide a generic interface to show records captured in

		the dying moments.  In the case of a panic the last part

		of the console log is captured, but other interesting

		data can also be saved.

		# mount -t pstore - /dev/pstore

		$ ls -l /dev/pstore

		total 0

		-r--r--r-- 1 root root 7896 Nov 30 15:38 dmesg-erst-1

		Different users of this interface will result in different

		filename prefixes.  Currently two are defined:

		"dmesg"	- saved console log

		"mce"	- architecture dependent data from fatal h/w error

		Once the information in a file has been read, removing

		the file will signal to the underlying persistent storage

		device that it can reclaim the space for later re-use.

		$ rm /dev/pstore/dmesg-erst-1

		The expectation is that all files in /dev/pstore

		will be saved elsewhere and erased from persistent store

		soon after boot to free up space ready for the next

		catastrophe.

		"disabled" to it.

		For the devices that are not capable of generating system wakeup

		events this file contains "\n".  In that cases the user space

		cannot modify the contents of this file and the device cannot be

		enabled to wake up the system.

		events this file is not present.  In that case the device cannot

		be enabled to wake up the system from sleep states.

What:		/sys/devices/.../power/control

Date:		January 2009

		The /sys/devices/.../wakeup_count attribute contains the number

		of signaled wakeup events associated with the device.  This

		attribute is read-only.  If the device is not enabled to wake up

		the system from sleep states, this attribute is empty.

		the system from sleep states, this attribute is not present.

What:		/sys/devices/.../power/wakeup_active_count

Date:		September 2010

		number of times the processing of wakeup events associated with

		the device was completed (at the kernel level).  This attribute

		is read-only.  If the device is not enabled to wake up the

		system from sleep states, this attribute is empty.

		system from sleep states, this attribute is not present.

What:		/sys/devices/.../power/wakeup_hit_count

Date:		September 2010

		number of times the processing of a wakeup event associated with

		the device might prevent the system from entering a sleep state.

		This attribute is read-only.  If the device is not enabled to

		wake up the system from sleep states, this attribute is empty.

		wake up the system from sleep states, this attribute is not

		present.

What:		/sys/devices/.../power/wakeup_active

Date:		September 2010

		or 0, depending on whether or not a wakeup event associated with

		the device is being processed (1).  This attribute is read-only.

		If the device is not enabled to wake up the system from sleep

		states, this attribute is empty.

		states, this attribute is not present.

What:		/sys/devices/.../power/wakeup_total_time_ms

Date:		September 2010

		the total time of processing wakeup events associated with the

		device, in milliseconds.  This attribute is read-only.  If the

		device is not enabled to wake up the system from sleep states,

		this attribute is empty.

		this attribute is not present.

What:		/sys/devices/.../power/wakeup_max_time_ms

Date:		September 2010

		the maximum time of processing a single wakeup event associated

		with the device, in milliseconds.  This attribute is read-only.

		If the device is not enabled to wake up the system from sleep

		states, this attribute is empty.

		states, this attribute is not present.

What:		/sys/devices/.../power/wakeup_last_time_ms

Date:		September 2010

		signaling the last wakeup event associated with the device, in

		milliseconds.  This attribute is read-only.  If the device is

		not enabled to wake up the system from sleep states, this

		attribute is empty.

		attribute is not present.

What:		/sys/devices/.../power/autosuspend_delay_ms

Date:		September 2010

What:		/sys/firmware/dmi/

Date:		February 2011

Contact:	Mike Waychison <mikew@google.com>

Description:

		Many machines' firmware (x86 and ia64) export DMI /

		SMBIOS tables to the operating system.  Getting at this

		information is often valuable to userland, especially in

		cases where there are OEM extensions used.

		The kernel itself does not rely on the majority of the

		information in these tables being correct.  It equally

		cannot ensure that the data as exported to userland is

		without error either.

		DMI is structured as a large table of entries, where

		each entry has a common header indicating the type and

		length of the entry, as well as 'handle' that is

		supposed to be unique amongst all entries.

		Some entries are required by the specification, but many

		others are optional.  In general though, users should

		never expect to find a specific entry type on their

		system unless they know for certain what their firmware

		is doing.  Machine to machine will vary.

		Multiple entries of the same type are allowed.  In order

		to handle these duplicate entry types, each entry is

		assigned by the operating system an 'instance', which is

		derived from an entry type's ordinal position.  That is

		to say, if there are 'N' multiple entries with the same type

		'T' in the DMI tables (adjacent or spread apart, it

		doesn't matter), they will be represented in sysfs as

		entries "T-0" through "T-(N-1)":

		Example entry directories:

			/sys/firmware/dmi/entries/17-0

			/sys/firmware/dmi/entries/17-1

			/sys/firmware/dmi/entries/17-2

			/sys/firmware/dmi/entries/17-3

			...

		Instance numbers are used in lieu of the firmware

		assigned entry handles as the kernel itself makes no

		guarantees that handles as exported are unique, and

		there are likely firmware images that get this wrong in

		the wild.

		Each DMI entry in sysfs has the common header values

		exported as attributes:

		handle	: The 16bit 'handle' that is assigned to this

			  entry by the firmware.  This handle may be

			  referred to by other entries.

		length	: The length of the entry, as presented in the

			  entry itself.  Note that this is _not the

			  total count of bytes associated with the

			  entry_.  This value represents the length of

			  the "formatted" portion of the entry.  This

			  "formatted" region is sometimes followed by

			  the "unformatted" region composed of nul

			  terminated strings, with termination signalled

			  by a two nul characters in series.

		raw	: The raw bytes of the entry. This includes the

			  "formatted" portion of the entry, the

			  "unformatted" strings portion of the entry,

			  and the two terminating nul characters.

		type	: The type of the entry.  This value is the same

			  as found in the directory name.  It indicates

			  how the rest of the entry should be

			  interpreted.

		instance: The instance ordinal of the entry for the

			  given type.  This value is the same as found

			  in the parent directory name.

		position: The position of the entry within the entirety

			  of the entirety.

		=== Entry Specialization ===

		Some entry types may have other information available in

		sysfs.

		--- Type 15 - System Event Log ---

		This entry allows the firmware to export a log of

		events the system has taken.  This information is

		typically backed by nvram, but the implementation

		details are abstracted by this table.  This entries data

		is exported in the directory:

		/sys/firmware/dmi/entries/15-0/system_event_log

		and has the following attributes (documented in the

		SMBIOS / DMI specification under "System Event Log (Type 15)":

		area_length

		header_start_offset

		data_start_offset

		access_method

		status

		change_token

		access_method_address

		header_format

		per_log_type_descriptor_length

		type_descriptors_supported_count

		As well, the kernel exports the binary attribute:

		raw_event_log	: The raw binary bits of the event log

				  as described by the DMI entry.