Files
linux/Documentation/ABI
Greg Kroah-Hartman 6a8b25abf1 Merge tag 'iio-for-4.18a' 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 cleanup for the 4.18 cycle

A nice mix this time of excellent cleanups (many to send drivers
speeding toward staging graduations) and new drivers / device support.
A good part of this is Brian Masney's never ending task on the tsl2x7x
driver.  The end is in sight so hopefully we'll get that one out of
staging very soon!

New device support
* AD5686
  - Support AD5685R (was wrongly present as AD5685)
  - Support AD5672R, AD5676, AD5676, AD5684R and AD5686R 4 and 8 channel
    SPI DACs with various precisions.
  - Support AD5671R, AD5675R, AD5694, AD5694R, AD5695R, AD5696 and AD5696R
    I2C DACs with various percisions and numbers of channels.
* Analog front end rescale driver - New driver.
  - Support current sensing usings a shunt resistor.
  - Support simple voltage dividers.
  - support simple current sense amplifiers.
* TI dac5571
  - New driver and device bindings supporting:
    dac5571, dac6571, dac7571, dac5574, dac6574, dac7574,
    dac5573, dac6573 and dac7573
* Meson-adc
  - Support for Meson AXG with DT bindings.
* mpu6050
  - Support the mpu9255 which only requires additional WHOAMI entry and
    compatible string.
* st_lsm6dsx
  - Support for lsm330dlc combinded accelerometer and gyro sensors with
    DT bindings.
* stm32_adc
  - Add support for STM32MP1 with bindings.

Staging graduations
* adis16201 after some excelent cleanup by Himanshu Jha.
* adis16029 after some excelent cleanup by Shreeya Patel.

New features:
* ABI docs
  - Add core ABI docs for angle channels.
* inv_mpu6050
  - Provide support for the full range of interrupts the device
    supports.
* st_accel
  - Add SMO8840 ACPI ID seen in the wild on some Lenovo machines.
* stx104
  - Provide a multiple gpio get function.

Cleanups / Minor fixes
* core
  - Use new nested structure support to improve kernel-doc.
* ad2s1200
  - Use be16_to_cpup instead of opencoding.
* ad5686
  - Indentation tidy up.
  - Switch to SPDX
  - Refactor to allow various numbers of channels.
  - Refactor to separate core and SPI specific support, prior to
    addition of i2c equivalent devices.
* ad7606
  - Use drvdata directly from device rather than boucing via the
    platform_device structure.
* ad7746
  - Replace opencoded byte swapped i2c calls with _swapped variants.
  - White space and line break readability improvements.
  - Reorder includes and variable declarations where appropriate.
* ad7791
  - Changes to the AD ADC library used by this driver took in the
    sampling frequency.  This lead to be the wrong path being the one
    tied to the resulting attribute, so it didn't work, and a warning
    to be printed.
* ad7780
  - Remove apparent support for sampling frequency control on devices
    that don't support changing the sampling attributes.
* ade7854
  - Fix a read of the wrong number of bits.
  - Improve error handling on i2c read/write errors.
  - Rework i2c and spi code to reduce duplication.
* adis16201 (staging)
  - Improve meaning inherent in some macro names by adding units etc
    where relevant.
  - Adjust comments to improve detail and drop the irrelevant.
  - Rename register address definitions definitions to add a _REG
    postfix, clearly separating them from field definitions. Reorganize
    the definitions to group register address and fields.
  - Use sign_extend32 rather than open coding.
  - Reverse Xmas tree ordering where appropriate and align function args.
  - Remove unused headers.
  - Use GENMASK where appropriate instead of open coding.
* adis16209 (staging)
  - Indent field definitions to visually separate them from
    register address definitions.
  - Use reverse xmas tree ordering where appropriate.
  - Add some whitespace where it will help readability.
  - Drop some unused headers.
  - Use GENMASK where appropriate.
* ad2s1200
  - Drop unnecessary includes and reorder alphabetically.
  - Reverse xmas tree and blank line cleanups.
* atlas-ph-sensor
  - Use msleep instead of usleep_range where the precise value doesn't
    matter and the delays are long.
* bcm150
  - Drop transaction splitting as core now handles it.
* cros_ec
  - Move the shared header to the include/iio/common directory.
    This brings it inline with the other multiple type devices.
  - Use drvdata directly from device rather than boucing via the
    platform_device structure.
* hid-sensors
  - Use drvdata directly from device rather than boucing via the
    platform_device structure.
* inv_mpu6050
  - Clear out a second function definition for the same function.
  - Don't flush fifo when the iio buffer is full but just drop excess
    data.
  - Tidy up set_power_itg and ensure it is used in the right places.
  - Use set_power_itg rather than opencoding it again in the i2c mux
    control.
  - Make sure error paths disable the power if undoing power on.
  - Used managed devm_ functions during probe. Delete remove function.
  - Refactor to pull raw data read out of read_raw function.
  - Simplify data reading error paths.
  - Only enable the i2c mux for chips with the i2c aux bus (not icm20608)
  - Fix a potential deadlock due to varying lock ordering.
  - Fix an issue where first sample from gyro after enabling is unstable
    by dropping the first sample.
  - Fix an issue where the user_ctrl register is incorrectly overwritten.
  - Tidy up some grammar and spelling minor issus.
* mcp320x
  - Use vendor compatible strings.
* mcp4018
  - Switch to using i2c .probe_new.
* mcp4351
  - switch to using i2c .probe_new.
* meson-adc
  - rework handing on common ADC platform data so it can be shared
    across multiple families of SoCs.
* sca3000
  - Fix an error handling path if the ring configure fails.
* st_lsm6dsx
  - Fix a wrong fifo threshold mask (no actual effect)
* stm32-dfsdm
  - Style fixes and cleanups.
  - Check filter ID is in range and check spi-max-frequency.
* tsl2x7x (staging)
  - Drop some unnecessary function calls, unused variables and
    unnecessary local variables.
  - Fix wrong interrupt type.
  - Avoid unnecessary double clear of interrupt.
  - Simplify proximity calibration call which did various things
    unrelated to actually calibrating.
  - Separate control of the proximity and ALS interrupts.
  - Improve consistency of logging.
  - Separate ALS and proximity persistence settings as they have
    separate hardware controls.
  - Tidy up variable ordering.
  - Add Brian to copyright notice given consider work on this driver.
  - Take advantage of hardware support for I2C address auto increment.
  - Combine individuaal enable and period attributes for the two
    directions on the threshold events into a single value as the
    hardware doesn't separate them.
  - Move integration_time* attributes from light channel to
    intensity value as they effect the intensity readings directly
    and the light reading only indirectly.  Hence this better
    reflects reality. Also move the calibscale_available.
  - Avoid returning an error in the IRQ handler.
  - Hard code the reg value in _clear_interrupts as it only takes
    one value in the code.   Result is the function has little
    purpose so opencode the two remaining i2c_smbus_write_byte
    calls.
  - Drop some unnecessary checking of the chip status register.
  - Tidy up return path in _write_interrupt_config.
  - Tidy up the ID verification code.
  - Move the power and diode settings defines into the header as these
    are needed for platform data configuration.
  - Various renames and comment cleanups for consistency and clarity.
  - Use actual device defaults for default startup settings.
  - SPDX
  - Add some range sanity checking to sysfs attribute writes.
  - Don't provide event interfaces if the interrupt line isn't available.
  - Use IIO_CONST_ATTR macro for calibscale_available as it's a constant
    string.
  - Fix the integration time and lux equations.
  - Make device IDs explicit index values in the device_channel_config array.
2018-05-11 09:50:04 +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.