linux/Documentation/ABI
Linus Torvalds eeb91e4f9d More ACPI and power management fixes and updates for 3.15-rc1
- Fix for a recently introduced CPU hotplug regression in ARM KVM
    from Ming Lei.
 
  - Fixes for breakage in the at32ap, loongson2_cpufreq, and unicore32
    cpufreq drivers introduced during the 3.14 cycle (-stable material)
    from Chen Gang and Viresh Kumar.
 
  - New powernv cpufreq driver from Vaidyanathan Srinivasan, with bits
    from Gautham R Shenoy and Srivatsa S Bhat.
 
  - Exynos cpufreq driver fix preventing it from being included into
    multiplatform builds that aren't supported by it from Sachin Kamat.
 
  - cpufreq cleanups related to the usage of the driver_data field in
    struct cpufreq_frequency_table from Viresh Kumar.
 
  - cpufreq ppc driver cleanup from Sachin Kamat.
 
  - Intel BayTrail support for intel_idle and ACPI idle from Len Brown.
 
  - Intel CPU model 54 (Atom N2000 series) support for intel_idle from
    Jan Kiszka.
 
  - intel_idle fix for Intel Ivy Town residency targets from Len Brown.
 
  - turbostat updates (Intel Broadwell support and output cleanups)
    from Len Brown.
 
  - New cpuidle sysfs attribute for exporting C-states' target residency
    information to user space from Daniel Lezcano.
 
  - New kernel command line argument to prevent power domains enabled
    by the bootloader from being turned off even if they are not in use
    (for diagnostics purposes) from Tushar Behera.
 
  - Fixes for wakeup sysfs attributes documentation from Geert Uytterhoeven.
 
  - New ACPI video blacklist entry for ThinkPad Helix from Stephen Chandler
    Paul.
 
  - Assorted ACPI cleanups and a Kconfig help update from Jonghwan Choi,
    Zhihui Zhang, Hanjun Guo.
 
 /
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v2.0.22 (GNU/Linux)
 
 iQIcBAABCAAGBQJTRxLAAAoJEILEb/54YlRxnCwP/16UwO/eVE8SIi0TqQboikFC
 k8u7F3zgDYG+xPSzXlCR+J7thTxGueQlrb+aM18PYuMVgaw2rpy7U7SIqEk8s6oR
 uFnzZCWKA5ZebbZn+NlodnQaJmbgJxwsVJDuuechUka/e67CaIc54JULi2ynZ0lz
 Kg/nU3NJhu4S81cT5SOTkJ9xE63oxHcCwKbNqEmxn7x7ddFzGK/DThG67NMEnW1F
 vHbBTSyI6vmXXg1f9aobUtuo3PfJkkx5jD+nR1H2e6wmB64tW7JPVKV3mi6LJfYM
 ui/8/gNb3PUMHMX1QbL9EFbPxl9miQx2NJ7dgFKa1HZ/WPyiXpJjz7uGr9O3Fau3
 cFVREdaW8p2TAYWOEgH8luohhdK0j8UEpR/sEm0TrTjsK8wqczVf/hz6RraVJZiN
 ck6eVHjY6m3/bFQauZQ/r+DNeeNcdr+iLejgjbh/MXuF3j0kx+1dkKkzCEU2TgEZ
 9etF0uzjlgyXySyxNKBeSW13+ssVA6kF5/BHns7LHoxTfGu7Y4oVaWUi+j74i66O
 bc+2ileNal71mS4v9gomnj6Ffj8oH8KXFA7k0sEsAdwLZNgThB5bTppmY/U7Y5Ce
 hTS81tcGe2vOVQzF9iFOF7LNKKussAVAtrgkkrA8lJLeOTfQbIo4+fMhORxf3X/p
 3O7R/jc4cT+IXK8a2xRt
 =hGKg
 -----END PGP SIGNATURE-----

Merge tag 'pm+acpi-3.15-rc1-3' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm

Pull more ACPI and power management fixes and updates from Rafael Wysocki:
 "This is PM and ACPI material that has emerged over the last two weeks
  and one fix for a CPU hotplug regression introduced by the recent CPU
  hotplug notifiers registration series.

  Included are intel_idle and turbostat updates from Len Brown (these
  have been in linux-next for quite some time), a new cpufreq driver for
  powernv (that might spend some more time in linux-next, but BenH was
  asking me so nicely to push it for 3.15 that I couldn't resist), some
  cpufreq fixes and cleanups (including fixes for some silly breakage in
  a couple of cpufreq drivers introduced during the 3.14 cycle),
  assorted ACPI cleanups, wakeup framework documentation fixes, a new
  sysfs attribute for cpuidle and a new command line argument for power
  domains diagnostics.

  Specifics:

   - Fix for a recently introduced CPU hotplug regression in ARM KVM
     from Ming Lei.

   - Fixes for breakage in the at32ap, loongson2_cpufreq, and unicore32
     cpufreq drivers introduced during the 3.14 cycle (-stable material)
     from Chen Gang and Viresh Kumar.

   - New powernv cpufreq driver from Vaidyanathan Srinivasan, with bits
     from Gautham R Shenoy and Srivatsa S Bhat.

   - Exynos cpufreq driver fix preventing it from being included into
     multiplatform builds that aren't supported by it from Sachin Kamat.

   - cpufreq cleanups related to the usage of the driver_data field in
     struct cpufreq_frequency_table from Viresh Kumar.

   - cpufreq ppc driver cleanup from Sachin Kamat.

   - Intel BayTrail support for intel_idle and ACPI idle from Len Brown.

   - Intel CPU model 54 (Atom N2000 series) support for intel_idle from
     Jan Kiszka.

   - intel_idle fix for Intel Ivy Town residency targets from Len Brown.

   - turbostat updates (Intel Broadwell support and output cleanups)
     from Len Brown.

   - New cpuidle sysfs attribute for exporting C-states' target
     residency information to user space from Daniel Lezcano.

   - New kernel command line argument to prevent power domains enabled
     by the bootloader from being turned off even if they are not in use
     (for diagnostics purposes) from Tushar Behera.

   - Fixes for wakeup sysfs attributes documentation from Geert
     Uytterhoeven.

   - New ACPI video blacklist entry for ThinkPad Helix from Stephen
     Chandler Paul.

   - Assorted ACPI cleanups and a Kconfig help update from Jonghwan
     Choi, Zhihui Zhang, Hanjun Guo"

* tag 'pm+acpi-3.15-rc1-3' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm: (28 commits)
  ACPI: Update the ACPI spec information in Kconfig
  arm, kvm: fix double lock on cpu_add_remove_lock
  cpuidle: sysfs: Export target residency information
  cpufreq: ppc: Remove duplicate inclusion of fsl_soc.h
  cpufreq: create another field .flags in cpufreq_frequency_table
  cpufreq: use kzalloc() to allocate memory for cpufreq_frequency_table
  cpufreq: don't print value of .driver_data from core
  cpufreq: ia64: don't set .driver_data to index
  cpufreq: powernv: Select CPUFreq related Kconfig options for powernv
  cpufreq: powernv: Use cpufreq_frequency_table.driver_data to store pstate ids
  cpufreq: powernv: cpufreq driver for powernv platform
  cpufreq: at32ap: don't declare local variable as static
  cpufreq: loongson2_cpufreq: don't declare local variable as static
  cpufreq: unicore32: fix typo issue for 'clk'
  cpufreq: exynos: Disable on multiplatform build
  PM / wakeup: Correct presence vs. emptiness of wakeup_* attributes
  PM / domains: Add pd_ignore_unused to keep power domains enabled
  ACPI / dock: Drop dock_device_ids[] table
  ACPI / video: Favor native backlight interface for ThinkPad Helix
  ACPI / thermal: Fix wrong variable usage in debug statement
  ...
2014-04-11 13:20:04 -07:00
..
obsolete
removed
stable powerpc/powernv Platform dump interface 2014-03-07 16:19:10 +11:00
testing More ACPI and power management fixes and updates for 3.15-rc1 2014-04-11 13:20:04 -07:00
README Documentation/ABI: document the non-ABI status of Kconfig and symbols 2013-11-13 12:09:32 +09:00

README

This directory attempts to document the ABI between the Linux kernel and
userspace, and the relative stability of these interfaces.  Due to the
everchanging nature of Linux, and the differing maturity levels, these
interfaces should be used by userspace programs in different ways.

We have four different levels of ABI stability, as shown by the four
different subdirectories in this location.  Interfaces may change levels
of stability according to the rules described below.

The different levels of stability are:

  stable/
	This directory documents the interfaces that the developer has
	defined to be stable.  Userspace programs are free to use these
	interfaces with no restrictions, and backward compatibility for
	them will be guaranteed for at least 2 years.  Most interfaces
	(like syscalls) are expected to never change and always be
	available.

  testing/
	This directory documents interfaces that are felt to be stable,
	as the main development of this interface has been completed.
	The interface can be changed to add new features, but the
	current interface will not break by doing this, unless grave
	errors or security problems are found in them.  Userspace
	programs can start to rely on these interfaces, but they must be
	aware of changes that can occur before these interfaces move to
	be marked stable.  Programs that use these interfaces are
	strongly encouraged to add their name to the description of
	these interfaces, so that the kernel developers can easily
	notify them if any changes occur (see the description of the
	layout of the files below for details on how to do this.)

  obsolete/
  	This directory documents interfaces that are still remaining in
	the kernel, but are marked to be removed at some later point in
	time.  The description of the interface will document the reason
	why it is obsolete and when it can be expected to be removed.

  removed/
	This directory contains a list of the old interfaces that have
	been removed from the kernel.

Every file in these directories will contain the following information:

What:		Short description of the interface
Date:		Date created
KernelVersion:	Kernel version this feature first showed up in.
Contact:	Primary contact for this interface (may be a mailing list)
Description:	Long description of the interface and how to use it.
Users:		All users of this interface who wish to be notified when
		it changes.  This is very important for interfaces in
		the "testing" stage, so that kernel developers can work
		with userspace developers to ensure that things do not
		break in ways that are unacceptable.  It is also
		important to get feedback for these interfaces to make
		sure they are working in a proper way and do not need to
		be changed further.


How things move between levels:

Interfaces in stable may move to obsolete, as long as the proper
notification is given.

Interfaces may be removed from obsolete and the kernel as long as the
documented amount of time has gone by.

Interfaces in the testing state can move to the stable state when the
developers feel they are finished.  They cannot be removed from the
kernel tree without going through the obsolete state first.

It's up to the developer to place their interfaces in the category they
wish for it to start out in.


Notable bits of non-ABI, which should not under any circumstances be considered
stable:

- Kconfig.  Userspace should not rely on the presence or absence of any
  particular Kconfig symbol, in /proc/config.gz, in the copy of .config
  commonly installed to /boot, or in any invocation of the kernel build
  process.

- Kernel-internal symbols.  Do not rely on the presence, absence, location, or
  type of any kernel symbol, either in System.map files or the kernel binary
  itself.  See Documentation/stable_api_nonsense.txt.