linux/Documentation/ABI
Greg Kroah-Hartman 4b55dce8b0 1st round of IIO new device support, features and cleanups in the 4.20 cycle.
There is a merge commit in here to pull in regmap support for repeatedly
 reading the same register (to read out FIFOs).  Used by the adxl372 driver.
 This will find uses elsewhere once we tidy up various drivers that are
 effectively doing this and relying on not enabling regcache.
 
 New device support
 * Analog devices ADXL372 accelerometer
   - new driver for this accelerometer including fifo and and interrupt support.
     Follow up patches enforce trigger validation, add sampling frequency
     control and filter bandwidth control.  A later series added i2c support
     to the existing SPI support.
 * ST lsm6dsx
   - rework and add support fo the LSM6DSO 6 axis mems sensor.
 * Linear LTC 1660 DAC
   - new driver supporting the LTC 1660 and LTC 1665 SPI DACs.
 * Microchip mcp3911 ADC.
   - new driver for this integrated analog front end and ADC.
 * Qualcomm SPMI PMIC5 adc driver
   - using the spmi framework, new driver and bindings for this ADC.
     Follow up patch adds some missing channels.
 
 Features
 * ad5758
   - support hard reset using a gpio (if provided).
 * mpu6050
   - Regulator support
 * qcom-spmi-adc5
   - Sanity check the channel numbers provided by DT to make sure the
     driver actually knows about them.
 * sc27xx
   - give raw data for channel 20 as it's used on all known boards for
     the headset which needs a custom converstion function.  If it turns
     out someone builds a board where this isn't true we will deal with it
     when it happens.
   - add ADC scale calibration.
 * tsl2772
   - support device tree binding to set the proximity led settings.
   - regulator supprot.
   - binding for apds9930 - trivial addition as register compatible with tsl2772.
 
 Cleanups / Minor fixes
 
 * adxl345
   - supress a static checker warning but explicitly checking if the id
     object is null.
 * bh1750
   - avoid CONFIG_PM_SLEEP checks.
   - SPDX.
 * bme680
   - spelling mistake
   - use clamp rather than open coding.
   - white space and other similar fixes.
   - rename MSK to MASK for clarifty and use GENMASK to specify them.
   - use the FIELD_GET macro rather than a very odd accessor of dividing by
     16 to get the shift.
   - rework to share handing for oversampling of the various channels in a
     unified way.
   - check explicitly for val2 in write_raw function to ensure it is 0.
   - drop some field defines that don't add anything.
 * dpot-adc
   - SPDX
 * envelope detector
   - SPDX
 * isl29501
   - fix an ancient compiler warning mostly because it results in much
     nicer code.
 * max30102
   - mark switch fall throughs.
 * max44000
   - drop an unused variable.
 * max512
   - avoid CONFIG_PM_SLEEP checks.
 * max5481
   - use of_device_get_match_data rather than open coding it.
 * max5821
   - avoid CONFIG_PM_SLEEP checks.
 * max9611
   - explicity cast an enum to an integer to make it totally clear that
     this is intended.
 * mcp4018
   - fix an inconsistent MODULE_LICENSE.
   - use of_device_get_match_data rather than open coding it.
 * mcp4531
   - use of_device_get_match_data rather than open coding it.
   - SPDX
 * mcp4725
   - avoid CONFIG_PM_SLEEP checks.
 * mcp4922
   - Fix error handling and prevent writing a negative to when setting the
     output voltage.
 * ms5611
   - drop deprecated compatible strings without manufacturer from being
     explicitly listed.  They are handled anyway.
   - SPDX
 * multiplexer
   - SPDX
 * qcom-vadc
   - fix inconsistent documentation for reg.
 * ti-dac5571
   - provide and of_match_table.
 
 * treewide
   - update Michael Hennerich's email address.
   - Use %pOFn rather than device_node.name.
 * documentation.
   - tidy up a wrong kernel version for the introduction of the
     position_relative ABI.
 -----BEGIN PGP SIGNATURE-----
 
 iQJFBAABCAAvFiEEbilms4eEBlKRJoGxVIU0mcT0FogFAluave0RHGppYzIzQGtl
 cm5lbC5vcmcACgkQVIU0mcT0Fogr/A//bfXkfYPO2tPQOe+Ut/isyKvceDFs4faJ
 0ogmVxrH5hwFe96vfB0RWcYhovKXONrRtqreMCiVPMjKxg5o+F3Q+eSj0qhxhG77
 bDV5CnF1GXiBe/02WSEs9B3L4oxu6Z/PGq2sGrlTfTy8NZxJW6biER1aWeBbxmR6
 nPBb9SXH4vuqiiF8UOwRB2ETelx2jXXCNFxmUVQ0bzCYgAp/n7B2ZJu6OxWIhBGC
 NEPYofFajNATJEGgTQmwmKNv6xL4wVSpZXMLO1hzKPe8arARBqPGjIg14srl+nWs
 HsOdsl/GkeOcPsI7aUvQO0zC5nOgU9iXtQFZQLq8D1xMQP9LzfRuLhymy8dH8hg+
 uUfxkJf0OwhqEW+6GJ0g4A2xaDHyM7JFQAV1/XCNS93qjpcgC7rcLbnSDy9u6SC/
 j3g3EFUXVYqOuFXbr+1TLrg/oJhnOkXp3Wbm/Di0zXJNYOtzQ9zSLp55HZLxvOOl
 zzLWCSkse9EAwHzVnl4BAd03Zw3Ewh9aAJlXQ7JKGtQSXo+PpFyIiyn8woQpzGV8
 OePhhmooOYVxI2Aua0UKhwa6lPeZT71zjpJyFCTFJqRwU3I/8HEDH5g+9dX6Vk6h
 CLF/fCLCkRa1ccDzFQbHai91xLflaYUsXdjOnQymJ5CYToni/IyPukrZ05b2IdvO
 XnMIaoVrAUU=
 =+9gG
 -----END PGP SIGNATURE-----

Merge tag 'iio-for-4.20a' of git://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio into staging-next

Jonathan writes:

1st round of IIO new device support, features and cleanups in the 4.20 cycle.

There is a merge commit in here to pull in regmap support for repeatedly
reading the same register (to read out FIFOs).  Used by the adxl372 driver.
This will find uses elsewhere once we tidy up various drivers that are
effectively doing this and relying on not enabling regcache.

New device support
* Analog devices ADXL372 accelerometer
  - new driver for this accelerometer including fifo and and interrupt support.
    Follow up patches enforce trigger validation, add sampling frequency
    control and filter bandwidth control.  A later series added i2c support
    to the existing SPI support.
* ST lsm6dsx
  - rework and add support fo the LSM6DSO 6 axis mems sensor.
* Linear LTC 1660 DAC
  - new driver supporting the LTC 1660 and LTC 1665 SPI DACs.
* Microchip mcp3911 ADC.
  - new driver for this integrated analog front end and ADC.
* Qualcomm SPMI PMIC5 adc driver
  - using the spmi framework, new driver and bindings for this ADC.
    Follow up patch adds some missing channels.

Features
* ad5758
  - support hard reset using a gpio (if provided).
* mpu6050
  - Regulator support
* qcom-spmi-adc5
  - Sanity check the channel numbers provided by DT to make sure the
    driver actually knows about them.
* sc27xx
  - give raw data for channel 20 as it's used on all known boards for
    the headset which needs a custom converstion function.  If it turns
    out someone builds a board where this isn't true we will deal with it
    when it happens.
  - add ADC scale calibration.
* tsl2772
  - support device tree binding to set the proximity led settings.
  - regulator supprot.
  - binding for apds9930 - trivial addition as register compatible with tsl2772.

Cleanups / Minor fixes

* adxl345
  - supress a static checker warning but explicitly checking if the id
    object is null.
* bh1750
  - avoid CONFIG_PM_SLEEP checks.
  - SPDX.
* bme680
  - spelling mistake
  - use clamp rather than open coding.
  - white space and other similar fixes.
  - rename MSK to MASK for clarifty and use GENMASK to specify them.
  - use the FIELD_GET macro rather than a very odd accessor of dividing by
    16 to get the shift.
  - rework to share handing for oversampling of the various channels in a
    unified way.
  - check explicitly for val2 in write_raw function to ensure it is 0.
  - drop some field defines that don't add anything.
* dpot-adc
  - SPDX
* envelope detector
  - SPDX
* isl29501
  - fix an ancient compiler warning mostly because it results in much
    nicer code.
* max30102
  - mark switch fall throughs.
* max44000
  - drop an unused variable.
* max512
  - avoid CONFIG_PM_SLEEP checks.
* max5481
  - use of_device_get_match_data rather than open coding it.
* max5821
  - avoid CONFIG_PM_SLEEP checks.
* max9611
  - explicity cast an enum to an integer to make it totally clear that
    this is intended.
* mcp4018
  - fix an inconsistent MODULE_LICENSE.
  - use of_device_get_match_data rather than open coding it.
* mcp4531
  - use of_device_get_match_data rather than open coding it.
  - SPDX
* mcp4725
  - avoid CONFIG_PM_SLEEP checks.
* mcp4922
  - Fix error handling and prevent writing a negative to when setting the
    output voltage.
* ms5611
  - drop deprecated compatible strings without manufacturer from being
    explicitly listed.  They are handled anyway.
  - SPDX
* multiplexer
  - SPDX
* qcom-vadc
  - fix inconsistent documentation for reg.
* ti-dac5571
  - provide and of_match_table.

* treewide
  - update Michael Hennerich's email address.
  - Use %pOFn rather than device_node.name.
* documentation.
  - tidy up a wrong kernel version for the introduction of the
    position_relative ABI.
2018-09-14 10:38:48 +02:00
..
obsolete usb: typec: Bus type for alternate modes 2018-07-02 17:42:36 +02:00
removed acpi, nfit: Remove ecc_unit_size 2018-06-03 12:49:15 -07:00
stable platform-drivers-x86 for v4.19-1 2018-08-22 14:14:15 -07:00
testing 1st round of IIO new device support, features and cleanups in the 4.20 cycle. 2018-09-14 10:38:48 +02:00
README docs: fix locations of several documents that got moved 2016-10-24 08:12:35 -02: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/process/stable-api-nonsense.rst.