linux/Documentation/ABI
Linus Torvalds eb7046e9bf platform-drivers-x86 for v4.20-1
Move the Dell dcdbas and dell_rbu drivers into platform/drivers/x86 as
 they are closely coupled with other drivers in this location.
 
 Improve _init* usage for acerhdf and fix some usage issues with messages
 and module parameters.
 
 Simplify asus-wmi by calling ACPI/WMI methods directly, eliminating
 workqueue overhead, eliminate double reporting of keyboard backlight.
 
 Fix wake from USB failure on Bay Trail devices (intel_int0002_vgpio).
 
 Notify intel_telemetry users when IPC1 device is not enabled.
 
 Update various drivers with new laptop model IDs.
 
 Update several intel drivers to use SPDX identifers and order headers
 alphabetically.
 
 The following is an automated git shortlog grouped by driver:
 
 Add Intel AtomISP2 dummy / power-management driver:
  - Add Intel AtomISP2 dummy / power-management driver
 
 lg-laptop:
  - Add LG Gram laptop special features driver
 
 HID:
  -  asus: only support backlight when it's not driven by WMI
 
 MAINTAINERS:
  -  intel_telemetry: Update maintainers info
  -  intel_pmc_core: Update MAINTAINERS
  -  Update maintainer for dcdbas and dell_rbu
  -  Use my infradead account exclusively for PDx86 work
 
 acerhdf:
  -  restructure to allow large BIOS table be __initconst
  -  mark appropriate content with __init prefix
  -  Add BIOS entry for Gateway LT31 v1.3307
  -  Remove cut-and-paste trap from instructions
  -  Enable ability to list supported systems
  -  clarify modinfo messages for BIOS override
 
 asus-wmi:
  -  export function for evaluating WMI methods
  -  Only notify kbd LED hw_change by fn-key pressed
  -  Simplify the keyboard brightness updating process
 
 firmware:
  -  dcdbas: include linux/io.h
  -  dcdbas: Move dcdbas to drivers/platform/x86
  -  dell_rbu: Move dell_rbu to drivers/platform/x86
  -  dcdbas: Add support for WSMT ACPI table
  -  dell_rbu: Make payload memory uncachable
 
 ideapad-laptop:
  -  Add Y530-15ICH to no_hw_rfkill
  -  Use __func__ instead of read_ec_cmd in pr_err
 
 intel-hid:
  -  Convert to use SPDX identifier
 
 intel-ips:
  -  Convert to use SPDX identifier
 
 intel-rst:
  -  Convert to use SPDX identifier
  -  Sort headers alphabetically
 
 intel-smartconnect:
  -  Convert to use SPDX identifier
  -  Sort headers alphabetically
 
 intel-wmi-thunderbolt:
  -  Add dynamic debugging
  -  Convert to use SPDX identifier
 
 intel_bxtwc_tmu:
  -  Convert to use SPDX identifier
 
 intel_cht_int33fe:
  -  Convert to use SPDX identifier
 
 intel_chtdc_ti_pwrbtn:
  -  Add SPDX identifier
 
 intel_int0002_vgpio:
  -  Convert to use SPDX identifier
  -  Implement irq_set_wake
  -  Enable the driver on Bay Trail platforms
 
 intel_menlow:
  -  Convert to use SPDX identifier
  -  Sort headers alphabetically
 
 intel_mid_powerbtn:
  -  Convert to use SPDX identifier
  -  Remove unnecessary init.h inclusion
  -  Get rid of custom ICPU() macro
 
 intel_mid_thermal:
  -  Convert to use SPDX identifier
  -  Sort headers alphabetically
 
 intel_oaktrail:
  -  Convert to use SPDX identifier
  -  Sort headers alphabetically
 
 intel_pmc:
  -  Convert to use SPDX identifier
  -  Sort headers alphabetically
 
 intel_punit_ipc:
  -  Convert to use SPDX identifier
  -  Sort headers alphabetically
 
 intel_scu_ipc:
  -  Convert to use SPDX identifier
  -  Sort headers alphabetically
 
 intel_telemetry:
  -  Get rid of custom macro
  -  report debugfs failure
  -  Convert to use SPDX identifier
 
 intel_turbo_max_3:
  -  Convert to use SPDX identifier
  -  Sort headers alphabetically
 
 mlx-platform:
  -  Properly use mlxplat_mlxcpld_msn201x_items
 
 touchscreen_dmi:
  -  Add min-x and min-y settings for various models
  -  Add info for the Onda V80 Plus v3 tablet
  -  Add info for the Trekstor Primetab T13B tablet
  -  Add info for the Trekstor Primebook C11 convertible
 
 tracing:
  -  Trivia spelling fix containerof() -> container_of()
 
 wmi:
  -  declare device_type structure as constant
 -----BEGIN PGP SIGNATURE-----
 
 iQEcBAABAgAGBQJb2mDCAAoJEKbMaAwKp364KdkH/Rar8cenw7uFeVzT5o4fGzTn
 0Oo1Pnwh+hPgmQwmf8O/mHsa/1Zb9nX4nNLU/ysDUjAAZ9wZLoB57HlImQquPA74
 c8lXTz5MVF140WB1f1Ck5PmeonJR2Xve7HTYCoBmGo71jOxHxCgJbp1Giiho0Imd
 3NXzzahEnAiy/L5PhqqYTmIfTeAHQ2Fo7GkHCjMnS20FP2fBtvPrc7db03F+FZ4y
 QTfbT0oR42NdeW21AbCRGY3P47axB3xDJX4LOYrb4uo4CIzd1yatlHk407NRRyv8
 pab6aeJR23FouA/tcvv+T36D3vqRw78e6BWdoyowWOd7CUOgjtSC3lKGzfT6hSY=
 =0BDZ
 -----END PGP SIGNATURE-----

Merge tag 'platform-drivers-x86-v4.20-1' of git://git.infradead.org/linux-platform-drivers-x86

Pull x86 platform driver updates from Darren Hart:

 - Move the Dell dcdbas and dell_rbu drivers into platform/drivers/x86
   as they are closely coupled with other drivers in this location.

 - Improve _init* usage for acerhdf and fix some usage issues with
   messages and module parameters.

 - Simplify asus-wmi by calling ACPI/WMI methods directly, eliminating
   workqueue overhead, eliminate double reporting of keyboard backlight.

 - Fix wake from USB failure on Bay Trail devices (intel_int0002_vgpio).

 - Notify intel_telemetry users when IPC1 device is not enabled.

 - Update various drivers with new laptop model IDs.

 - Update several intel drivers to use SPDX identifers and order headers
   alphabetically.

* tag 'platform-drivers-x86-v4.20-1' of git://git.infradead.org/linux-platform-drivers-x86: (64 commits)
  HID: asus: only support backlight when it's not driven by WMI
  platform/x86: asus-wmi: export function for evaluating WMI methods
  platform/x86: asus-wmi: Only notify kbd LED hw_change by fn-key pressed
  platform/x86: wmi: declare device_type structure as constant
  platform/x86: ideapad: Add Y530-15ICH to no_hw_rfkill
  platform/x86: Add Intel AtomISP2 dummy / power-management driver
  platform/x86: touchscreen_dmi: Add min-x and min-y settings for various models
  platform/x86: touchscreen_dmi: Add info for the Onda V80 Plus v3 tablet
  platform/x86: touchscreen_dmi: Add info for the Trekstor Primetab T13B tablet
  platform/x86: intel_telemetry: Get rid of custom macro
  platform/x86: intel_telemetry: report debugfs failure
  MAINTAINERS: intel_telemetry: Update maintainers info
  platform/x86: Add LG Gram laptop special features driver
  platform/x86: asus-wmi: Simplify the keyboard brightness updating process
  platform/x86: touchscreen_dmi: Add info for the Trekstor Primebook C11 convertible
  platform/x86: mlx-platform: Properly use mlxplat_mlxcpld_msn201x_items
  MAINTAINERS: intel_pmc_core: Update MAINTAINERS
  firmware: dcdbas: include linux/io.h
  platform/x86: intel-wmi-thunderbolt: Add dynamic debugging
  platform/x86: intel-wmi-thunderbolt: Convert to use SPDX identifier
  ...
2018-11-01 08:42:21 -07: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 usb: usbtmc: Remove sysfs group TermChar and auto_abort 2018-09-20 13:04:03 +02:00
testing platform-drivers-x86 for v4.20-1 2018-11-01 08:42:21 -07: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.