linux-stable/Documentation/ABI
Greg Kroah-Hartman 6e49557b31 First round of IIO new drivers, cleanups and functionality for the 3.20 cycle take 2
Updated pull request with Daniel's fix on top for the power management
 Kconfig changes that had snuck in since last update of the IIO tree
 worked it's way through from mainline.
 
 Original pull message
 
 New device support
 * jsa1212 proxmity / ambient light sensor
 * SM08500 supported added to the kxcjk-1013 accelerometer driver
 * KMX61 Accelerometer/Magnetometer.  This took a somewhat rocky path
   being first merged, then reverted for a rewrite after a discussion of
   how to support additional functionality and finally being merged prior
   to some last reviews coming in, with resultant follow up patches.
 * Freescale mma9551l driver (minor follow up warning supression patch).
 * Semtech SX9500 proximity device driver.
 * ak8975 gains support for ak09911 and ak09912 and drop the standalone driver
   for the ak09911.
 
 New functionality
  * Dummy driver gains some virtual registers making it more flexible.
  * IIO_ACTIVITY channel types, with modifiers running, walking etc.  This is
    to support on chip motion clasifiers.  As such it is in the form of a
    confidence percentage.  The only devices so far only do binary decisions
    but this gives us room when other devices give more nuanced clasification.
  * IIO_EV_DIR_NONE type for events where there is no obvious direction.
    First case is step detection.
  * IIO_STEPS channel type for pedometers.
  * ENABLE mask element used to control turning on counting types such as
    the pedometer that need a 'start point'.
  * INSTANCE event type to support things that happen once.
  * info element for height calibration (used in various motion estimation
    algorithms). Note heigh tof use
  * dummy driver demonstration of the use of all the new bits above.
  * event monitor support for the new events.
  * inv_mpu6050 gains an i2c mux to allow bypassing the device to access
    additional devices connected on the other side of it.  Note that in
    Windows these are handled by firmware on the device and not exposed
    directly.
  * inv_mpu6050 gains ACPI enumeration.
  * inkern interface gains iio_write_channel_raw to allow in kernel users
    of DAC functionality via a simple wrapper.
  * Document input current readings in the ABI docs.
  * Add an error message when we get an out of range error in device tree
    processing for the in kernel interfaces.  Basically a device tree debugging
    aid.
  * Add a sanity check that a scan index for a channel is unique during
    registration.  There to help catch bugs as this should never happen
    in a bug free driver.
 
 Cleanups and fixlets
 
  A rework of buffer registration from Lars - a precursor to some other
  upcoming new stuff (a few patches from others rolled in here as well).
  * Ensure all drivers register the same channels for the device and buffer.
  * Move buffer registration into the core rather than using the old
    two step approach.  Now we have simple ways of using a unified set channels
    for both without requiring channels be exposed by both interface, this
    removes a fair bit of boilerplate.
  * Stop sca3000 and ad5933 (both in staging) enabling buffer channels by
    default. It has long be convention in IIO to startup with no channels
    enabled and leave it up to userspace to say what goes in the buffer.
    Getting rid of these allows us to drop export of iio_scan_mask_set.
  * Drop get_bytes_per_datum from iio_buffer_access_funcs as not been used
    for a while.
  * Allocate standard buffer attributes in the core rather than in every
    driver with a buffer.
  * Make the length attribute read only when a driver is not able to set
    the length.
  * Drop the get_length callback for buffers as it is already available in
    struct iio_buffer.
  * Drop an unused arguement form iio_kfifo_allocate and add devm allocator
    for it.
  * some kconfig entries gain anotation with the resulting module name.
  * Fix a resulting compile issue in dummy driver due to a stub taking
    wrong parameters as a result of the above rework.
  * Fix an off by 2 error in copying the core assigned buffer attributes.
 
 Other cleanups,
  * Trivial space before comma fixups.
  * ak8975 fixlets - none critical.  Rework to allow more device support.
  * Drop unnecessary sizeof(u8) calls.
  * bmp280 - refactor the compensation code to reduce copy operations and
    code length.  A second patch futher optimized this and performed some
    other minor cleanups.
  * kxcjk-1013 - various power control cleanups to avoid unnecessary enable
    / disable of device.  Make sure it is only controlled at all if CONFIG_PM
    is enabled.  Also som cleanups of error paths.
  * Small cleanups in adf4530 driver - pointless message and unnecessary braces.
  * Clarifiy the proximity ABI docs to make it clear it should get bigger
    as we move futher away.
  * Drop a misleading comment form industrialio-core.c
  * Trivial white space cleanups.
  * sca3000 looses an unused debug function.
  * Fix char unsigned ordering in ad8366
  * Increase the sleep time in ad9523 to make it predictable (value didn't
    really matter so make it more than 20 msecs)
  * mxs-lradc touchscreen property cleanups in device tree are fixed to ensure
    the meet all the 'interesting' documentation.
  * A couple of cleanups for the staging ad5933 driver to avoid unnecessary
    conversion to a processed temperature vlaue in kernel and remove
    platform data form the state structure as not needed after probe.
  * Fix a wrong scale factor in the docs.
 
 Misc
  * Add IIO include files to the maintainers entry.
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v2
 
 iQIcBAABCAAGBQJUvtDlAAoJEFSFNJnE9BaIaNMQAI9ZYOrOmvSpxPV4ab71it9z
 gi03VG8+iJl0dPgwcSHeFZvSDiNAOWSX/XdWLoxFAdpjpsnytIp01s9+c3ogz58j
 pYbjxuOT2Qcf+36REuaFkQPFV2ppXMvwDwFUUNeFVupu+bVUKeZuNafBDp00aN1c
 o4MPDwoS1EcTHL+77iCg06exL8LozOwLabfUTRVIRkhIqikemghcmubQHH06m+dk
 EMddtNcXTVR4cJLX076nkKsNDHgmfoBYL9Hy/OvQbjWYAxoZg+q90ZX8yCy0Z5oW
 otChj5XpoYRIa7X6xvP5kTebD4iiR/COWer83EyqFosXhmQ/27rWasST42j1K3q/
 mU40skbscDef4F6COMlgBtVh1FhKUm9AHPAGk5swW792Qjpd4xdt+GShU5bJCa4O
 OOZYk8ulraELeWVz2IK+CrOvJYeTSrNQR6VA6sBjWRHeqxtB0yOJkhxX9NUcSIgJ
 GwM8qNTrQUkvI7OGvFGvf8hp9cboJTKEfzC+yspj+OJSjgJgNWw2pOjzJjsexxaL
 nT2rKhPg46hC+FR4IvPPjhGihCtMSgBWkwbHSeXH+TgRfbbTUh6y6sqEUZraVhnQ
 LKde54G0aH1XBFIM6fwWIPgdWBWsI3b3pFuBRMzhORdcCuAUOvDSyc5hVcaA8qb5
 UZghapUruB556xjoMV3n
 =LlJD
 -----END PGP SIGNATURE-----

Merge tag 'iio-for-3.20a_take2' of git://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio into staging-testing

Jonathan writes:

First round of IIO new drivers, cleanups and functionality for the 3.20 cycle take 2

Updated pull request with Daniel's fix on top for the power management
Kconfig changes that had snuck in since last update of the IIO tree
worked it's way through from mainline.

Original pull message

New device support
* jsa1212 proxmity / ambient light sensor
* SM08500 supported added to the kxcjk-1013 accelerometer driver
* KMX61 Accelerometer/Magnetometer.  This took a somewhat rocky path
  being first merged, then reverted for a rewrite after a discussion of
  how to support additional functionality and finally being merged prior
  to some last reviews coming in, with resultant follow up patches.
* Freescale mma9551l driver (minor follow up warning supression patch).
* Semtech SX9500 proximity device driver.
* ak8975 gains support for ak09911 and ak09912 and drop the standalone driver
  for the ak09911.

New functionality
 * Dummy driver gains some virtual registers making it more flexible.
 * IIO_ACTIVITY channel types, with modifiers running, walking etc.  This is
   to support on chip motion clasifiers.  As such it is in the form of a
   confidence percentage.  The only devices so far only do binary decisions
   but this gives us room when other devices give more nuanced clasification.
 * IIO_EV_DIR_NONE type for events where there is no obvious direction.
   First case is step detection.
 * IIO_STEPS channel type for pedometers.
 * ENABLE mask element used to control turning on counting types such as
   the pedometer that need a 'start point'.
 * INSTANCE event type to support things that happen once.
 * info element for height calibration (used in various motion estimation
   algorithms). Note heigh tof use
 * dummy driver demonstration of the use of all the new bits above.
 * event monitor support for the new events.
 * inv_mpu6050 gains an i2c mux to allow bypassing the device to access
   additional devices connected on the other side of it.  Note that in
   Windows these are handled by firmware on the device and not exposed
   directly.
 * inv_mpu6050 gains ACPI enumeration.
 * inkern interface gains iio_write_channel_raw to allow in kernel users
   of DAC functionality via a simple wrapper.
 * Document input current readings in the ABI docs.
 * Add an error message when we get an out of range error in device tree
   processing for the in kernel interfaces.  Basically a device tree debugging
   aid.
 * Add a sanity check that a scan index for a channel is unique during
   registration.  There to help catch bugs as this should never happen
   in a bug free driver.

Cleanups and fixlets

 A rework of buffer registration from Lars - a precursor to some other
 upcoming new stuff (a few patches from others rolled in here as well).
 * Ensure all drivers register the same channels for the device and buffer.
 * Move buffer registration into the core rather than using the old
   two step approach.  Now we have simple ways of using a unified set channels
   for both without requiring channels be exposed by both interface, this
   removes a fair bit of boilerplate.
 * Stop sca3000 and ad5933 (both in staging) enabling buffer channels by
   default. It has long be convention in IIO to startup with no channels
   enabled and leave it up to userspace to say what goes in the buffer.
   Getting rid of these allows us to drop export of iio_scan_mask_set.
 * Drop get_bytes_per_datum from iio_buffer_access_funcs as not been used
   for a while.
 * Allocate standard buffer attributes in the core rather than in every
   driver with a buffer.
 * Make the length attribute read only when a driver is not able to set
   the length.
 * Drop the get_length callback for buffers as it is already available in
   struct iio_buffer.
 * Drop an unused arguement form iio_kfifo_allocate and add devm allocator
   for it.
 * some kconfig entries gain anotation with the resulting module name.
 * Fix a resulting compile issue in dummy driver due to a stub taking
   wrong parameters as a result of the above rework.
 * Fix an off by 2 error in copying the core assigned buffer attributes.

Other cleanups,
 * Trivial space before comma fixups.
 * ak8975 fixlets - none critical.  Rework to allow more device support.
 * Drop unnecessary sizeof(u8) calls.
 * bmp280 - refactor the compensation code to reduce copy operations and
   code length.  A second patch futher optimized this and performed some
   other minor cleanups.
 * kxcjk-1013 - various power control cleanups to avoid unnecessary enable
   / disable of device.  Make sure it is only controlled at all if CONFIG_PM
   is enabled.  Also som cleanups of error paths.
 * Small cleanups in adf4530 driver - pointless message and unnecessary braces.
 * Clarifiy the proximity ABI docs to make it clear it should get bigger
   as we move futher away.
 * Drop a misleading comment form industrialio-core.c
 * Trivial white space cleanups.
 * sca3000 looses an unused debug function.
 * Fix char unsigned ordering in ad8366
 * Increase the sleep time in ad9523 to make it predictable (value didn't
   really matter so make it more than 20 msecs)
 * mxs-lradc touchscreen property cleanups in device tree are fixed to ensure
   the meet all the 'interesting' documentation.
 * A couple of cleanups for the staging ad5933 driver to avoid unnecessary
   conversion to a processed temperature vlaue in kernel and remove
   platform data form the state structure as not needed after probe.
 * Fix a wrong scale factor in the docs.

Misc
 * Add IIO include files to the maintainers entry.
2015-01-21 10:13:37 +08: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 net_dma: simple removal 2014-09-28 07:05:16 -07:00
stable USB patches for 3.19-rc1 2014-12-14 14:57:16 -08:00
testing First round of IIO new drivers, cleanups and functionality for the 3.20 cycle take 2 2015-01-21 10:13:37 +08: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.