linux/Documentation/ABI
Linus Torvalds a727eaf64f ARM: SoC driver changes
SoC-near driver changes that we're merging through our tree. Mostly
 because they depend on other changes we have staged, but in some cases
 because the driver maintainers preferred that we did it this way.
 
 This contains a largeish cleanup series of the omap_l3_noc bus driver,
 cpuidle rework for Exynos, some reset driver conversions and a long
 branch of TI EDMA fixes and cleanups, with more to come next release.
 
 The TI EDMA cleanups is a shared branch with the dmaengine tree, with
 a handful of Davinci-specific fixes on top.
 
 After discussion at last year's KS (and some more on the mailing lists),
 we are here adding a drivers/soc directory. The purpose of this is
 to keep per-vendor shared code that's needed by different drivers but
 that doesn't fit into the MFD (nor drivers/platform) model. We expect
 to keep merging contents for this hierarchy through arm-soc so we can
 keep an eye on what the vendors keep adding here and not making it a
 free-for-all to shove in crazy stuff.
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.14 (GNU/Linux)
 
 iQIcBAABAgAGBQJTjOFiAAoJEIwa5zzehBx30RYP/0UE+R8ccdsodunmIDrmQ7QP
 qFWe1YTWlyXtGBDaPCNfdcU09UYatPKuCv5dJ2ToQCyyFI26PIIhFtnCNXmMuYz+
 XPCuqAlJ9hZWx7+j2hXRlyhoZMAaJ5EVVxaK5tnVYXDIfy1Y3xG7i069HD/qGrQp
 xrV+XofFmpU2VAds6S+SpecFFfYD7n/pJ1bTSgzPfaUsEUyV882dJ3skgs1VpTzQ
 PnL/0Z2t4ePoP3+6p+F7EnJxemLF5IXrlL0c7hODxQKuMqlzoUluywh6SwOHfCQL
 u2cc5SFUbbKhExwlGOVibdQMiC0HUOXyRvyYFOIdbv+xNH+Zc/tcoQQ22PWm4Yy1
 08qOm3Fr6yw5nH5IT+1wCIFCzJEC/ZHM5B2t+RISFybAMk6Bg1TDYJLmd570zkEL
 aTLtS5hdmy4h8Ad5FBtwKNyL//6FJJxhbHUu/m0qaE0phq94+78B2M6vbx6757xC
 kCFlpJsHoN0Tn5c9Q1hpTqI/BHxb4UR7Nf+b8Ox8Veuc9JrS35lzi/rWnGxB5WB0
 +1KCA8eih9KXTtksxAte1TmSbMciqW559RUR7dNAPXAMPksY2mJV1I+rg0cRsY3i
 F90Lnc6LWUM5PYpc4VwiC0sUCLKzTFnpZUELqMOiws3PUblbb0StXuoNo6owbtsK
 mp1Juxi1n7VhoN9AFVpL
 =SC+e
 -----END PGP SIGNATURE-----

Merge tag 'drivers-for-3.16' of git://git.kernel.org/pub/scm/linux/kernel/git/arm/arm-soc into next

Pull ARM SoC driver changes from Olof Johansson:
 "SoC-near driver changes that we're merging through our tree.  Mostly
  because they depend on other changes we have staged, but in some cases
  because the driver maintainers preferred that we did it this way.

  This contains a largeish cleanup series of the omap_l3_noc bus driver,
  cpuidle rework for Exynos, some reset driver conversions and a long
  branch of TI EDMA fixes and cleanups, with more to come next release.

  The TI EDMA cleanups is a shared branch with the dmaengine tree, with
  a handful of Davinci-specific fixes on top.

  After discussion at last year's KS (and some more on the mailing
  lists), we are here adding a drivers/soc directory.  The purpose of
  this is to keep per-vendor shared code that's needed by different
  drivers but that doesn't fit into the MFD (nor drivers/platform)
  model.  We expect to keep merging contents for this hierarchy through
  arm-soc so we can keep an eye on what the vendors keep adding here and
  not making it a free-for-all to shove in crazy stuff"

* tag 'drivers-for-3.16' of git://git.kernel.org/pub/scm/linux/kernel/git/arm/arm-soc: (101 commits)
  cpufreq: exynos: Fix driver compilation with ARCH_MULTIPLATFORM
  tty: serial: msm: Remove direct access to GSBI
  power: reset: keystone-reset: introduce keystone reset driver
  Documentation: dt: add bindings for keystone pll control controller
  Documentation: dt: add bindings for keystone reset driver
  soc: qcom: fix of_device_id table
  ARM: EXYNOS: Fix kernel panic when unplugging CPU1 on exynos
  ARM: EXYNOS: Move the driver to drivers/cpuidle directory
  ARM: EXYNOS: Cleanup all unneeded headers from cpuidle.c
  ARM: EXYNOS: Pass the AFTR callback to the platform_data
  ARM: EXYNOS: Move S5P_CHECK_SLEEP into pm.c
  ARM: EXYNOS: Move the power sequence call in the cpu_pm notifier
  ARM: EXYNOS: Move the AFTR state function into pm.c
  ARM: EXYNOS: Encapsulate the AFTR code into a function
  ARM: EXYNOS: Disable cpuidle for exynos5440
  ARM: EXYNOS: Encapsulate boot vector code into a function for cpuidle
  ARM: EXYNOS: Pass wakeup mask parameter to function for cpuidle
  ARM: EXYNOS: Remove ifdef for scu_enable in pm
  ARM: EXYNOS: Move scu_enable in the cpu_pm notifier
  ARM: EXYNOS: Use the cpu_pm notifier for pm
  ...
2014-06-02 16:35:49 -07:00
..
obsolete Merge branches 'for-3.7/upstream-fixes', 'for-3.8/hidraw', 'for-3.8/i2c-hid', 'for-3.8/multitouch', 'for-3.8/roccat', 'for-3.8/sensors' and 'for-3.8/upstream' into for-linus 2012-12-12 21:41:55 +01:00
removed netfilter: remove ip_queue support 2012-05-08 20:25:42 +02:00
stable powerpc/powernv Platform dump interface 2014-03-07 16:19:10 +11:00
testing ARM: SoC driver changes 2014-06-02 16:35:49 -07:00
README Documentation/ABI: document the non-ABI status of Kconfig and symbols 2013-11-13 12:09:32 +09:00

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.