linux/Documentation/ABI
Linus Torvalds 1464677662 platform-drivers-x86 for v5.18-1
Highlights:
 - new drivers:
   - AMD Host System Management Port (HSMP)
   - Intel Software Defined Silicon
 - removed drivers (functionality folded into other drivers):
   - intel_cht_int33fe_microb
   - surface3_button
 - amd-pmc:
   - s2idle bug-fixes
   - Support for AMD Spill to DRAM STB feature
 - hp-wmi:
   - Fix SW_TABLET_MODE detection method (and other fixes)
   - Support omen thermal profile policy v1
 - serial-multi-instantiate:
   - Add SPI device support
   - Add support for CS35L41 amplifiers used in new laptops
 - think-lmi:
   - syfs-class-firmware-attributes Certificate authentication support
 - thinkpad_acpi:
   - Fixes + quirks
   - Add platform_profile support on AMD based ThinkPads
 - x86-android-tablets
   - Improve Asus ME176C / TF103C support
   - Support Nextbook Ares 8, Lenovo Tab 2 830 and 1050 tablets
 - Lots of various other small fixes and hardware-id additions
 
 The following is an automated git shortlog grouped by driver:
 
 ACPI / scan:
  -  Create platform device for CS35L41
 
 ACPI / x86:
  -  Add support for LPS0 callback handler
 
 ALSA:
  -  hda/realtek: Add support for HP Laptops
 
 Add AMD system management interface:
  - Add AMD system management interface
 
 Add Intel Software Defined Silicon driver:
  - Add Intel Software Defined Silicon driver
 
 Documentation:
  -  syfs-class-firmware-attributes: Lenovo Certificate support
  -  Add x86/amd_hsmp driver
 
 ISST:
  -  Fix possible circular locking dependency detected
 
 Input:
  -  soc_button_array - add support for Microsoft Surface 3 (MSHW0028) buttons
 
 Merge remote-tracking branch 'pdx86/platform-drivers-x86-pinctrl-pmu_clk' into review-hans-gcc12:
  - Merge remote-tracking branch 'pdx86/platform-drivers-x86-pinctrl-pmu_clk' into review-hans-gcc12
 
 Merge tag 'platform-drivers-x86-serial-multi-instantiate-1' into review-hans:
  - Merge tag 'platform-drivers-x86-serial-multi-instantiate-1' into review-hans
 
 Replace acpi_bus_get_device():
  - Replace acpi_bus_get_device()
 
 amd-pmc:
  -  Only report STB errors when STB enabled
  -  Drop CPU QoS workaround
  -  Output error codes in messages
  -  Move to later in the suspend process
  -  Validate entry into the deepest state on resume
  -  uninitialized variable in amd_pmc_s2d_init()
  -  Set QOS during suspend on CZN w/ timer wakeup
  -  Add support for AMD Spill to DRAM STB feature
  -  Correct usage of SMU version
  -  Make amd_pmc_stb_debugfs_fops static
 
 asus-tf103c-dock:
  -  Make 2 global structs static
 
 asus-wmi:
  -  Fix regression when probing for fan curve control
 
 hp-wmi:
  -  support omen thermal profile policy v1
  -  Changing bios_args.data to be dynamically allocated
  -  Fix 0x05 error code reported by several WMI calls
  -  Fix SW_TABLET_MODE detection method
  -  Fix hp_wmi_read_int() reporting error (0x05)
 
 huawei-wmi:
  -  check the return value of device_create_file()
 
 i2c-multi-instantiate:
  -  Rename it for a generic serial driver name
 
 int3472:
  -  Add terminator to gpiod_lookup_table
 
 intel-uncore-freq:
  -  fix uncore_freq_common_init() error codes
 
 intel_cht_int33fe:
  -  Move to intel directory
  -  Drop Lenovo Yogabook YB1-X9x code
  -  Switch to DMI modalias based loading
 
 intel_crystal_cove_charger:
  -  Fix IRQ masking / unmasking
 
 lg-laptop:
  -  Move setting of battery charge limit to common location
 
 pinctrl:
  -  baytrail: Add pinconf group + function for the pmu_clk
 
 platform/dcdbas:
  -  move EXPORT_SYMBOL after function
 
 platform/surface:
  -  Remove Surface 3 Button driver
  -  surface3-wmi: Simplify resource management
  -  Replace acpi_bus_get_device()
  -  Reinstate platform dependency
 
 platform/x86/intel-uncore-freq:
  -  Split common and enumeration part
 
 platform/x86/intel/uncore-freq:
  -  Display uncore current frequency
  -  Use sysfs API to create attributes
  -  Move to uncore-frequency folder
 
 selftests:
  -  sdsi: test sysfs setup
 
 serial-multi-instantiate:
  -  Add SPI support
  -  Reorganize I2C functions
 
 spi:
  -  Add API to count spi acpi resources
  -  Support selection of the index of the ACPI Spi Resource before alloc
  -  Create helper API to lookup ACPI info for spi device
  -  Make spi_alloc_device and spi_add_device public again
 
 surface:
  -  surface3_power: Fix battery readings on batteries without a serial number
 
 think-lmi:
  -  Certificate authentication support
 
 thinkpad_acpi:
  -  consistently check fan_get_status return.
  -  Don't use test_bit on an integer
  -  Fix compiler warning about uninitialized err variable
  -  clean up dytc profile convert
  -  Add PSC mode support
  -  Add dual fan probe
  -  Add dual-fan quirk for T15g (2nd gen)
  -  Fix incorrect use of platform profile on AMD platforms
  -  Add quirk for ThinkPads without a fan
 
 tools arch x86:
  -  Add Intel SDSi provisiong tool
 
 touchscreen_dmi:
  -  Add info for the RWC NANOTE P8 AY07J 2-in-1
 
 x86-android-tablets:
  -  Depend on EFI and SPI
  -  Lenovo Yoga Tablet 2 830/1050 sound support
  -  Workaround Lenovo Yoga Tablet 2 830/1050 poweroff hang
  -  Add Lenovo Yoga Tablet 2 830 / 1050 data
  -  Fix EBUSY error when requesting IOAPIC IRQs
  -  Minor charger / fuel-gauge improvements
  -  Add Nextbook Ares 8 data
  -  Add IRQ to Asus ME176C accelerometer info
  -  Add lid-switch gpio-keys pdev to Asus ME176C + TF103C
  -  Add x86_android_tablet_get_gpiod() helper
  -  Add Asus ME176C/TF103C charger and fuelgauge props
  -  Add battery swnode support
  -  Trivial typo fix for MODULE_AUTHOR
  -  Fix the buttons on CZC P10T tablet
  -  Constify the gpiod_lookup_tables arrays
  -  Add an init() callback to struct x86_dev_info
  -  Add support for disabling ACPI _AEI handlers
  -  Correct crystal_cove_charger module name
 -----BEGIN PGP SIGNATURE-----
 
 iQFIBAABCAAyFiEEuvA7XScYQRpenhd+kuxHeUQDJ9wFAmI8SjEUHGhkZWdvZWRl
 QHJlZGhhdC5jb20ACgkQkuxHeUQDJ9wYUwf/cdUMPFy5cwpHq1LuqGy+PxVCRHCe
 71PFd2Ycj+HGOtrt66RxSiCC1Seb4tylr7FvudToDaqWjlBf5n6LhpDudg4ds7Qw
 lCuRlaXTIrF7p3nOLIsWvJPRqacMG79KkRM62MLTS2evtRYjbnKvFzNPJPzr8827
 1AhCakE92S8gkR5lUZYYHtsaz9rZ4z4TrEtjO6GdlbL2bDw0l18dNNwdMomfVpNS
 bBIHIDLeufDuMJ4PxIHlE5MB3AuZAuc0HTJWihozyJX/h5FMGI6qVm0/s9RAfHgX
 XdMCpADtS/JjHCmkFgLZYIzvXTxwQVZRo5VO0Wrv5Mis6gSpxJXCd0aKlA==
 =1x9/
 -----END PGP SIGNATURE-----

Merge tag 'platform-drivers-x86-v5.18-1' of git://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86

Pull x86 platform driver updates from Hans de Goede:
  "New drivers:
    - AMD Host System Management Port (HSMP)
    - Intel Software Defined Silicon

  Removed drivers (functionality folded into other drivers):
    - intel_cht_int33fe_microb
    - surface3_button

  amd-pmc:
    - s2idle bug-fixes
    - Support for AMD Spill to DRAM STB feature

  hp-wmi:
    - Fix SW_TABLET_MODE detection method (and other fixes)
    - Support omen thermal profile policy v1

  serial-multi-instantiate:
    - Add SPI device support
    - Add support for CS35L41 amplifiers used in new laptops

  think-lmi:
    - syfs-class-firmware-attributes Certificate authentication support

  thinkpad_acpi:
    - Fixes + quirks
    - Add platform_profile support on AMD based ThinkPads

  x86-android-tablets:
    - Improve Asus ME176C / TF103C support
    - Support Nextbook Ares 8, Lenovo Tab 2 830 and 1050 tablets

  Lots of various other small fixes and hardware-id additions"

* tag 'platform-drivers-x86-v5.18-1' of git://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86: (60 commits)
  platform/x86: think-lmi: Certificate authentication support
  Documentation: syfs-class-firmware-attributes: Lenovo Certificate support
  platform/x86: amd-pmc: Only report STB errors when STB enabled
  platform/x86: amd-pmc: Drop CPU QoS workaround
  platform/x86: amd-pmc: Output error codes in messages
  platform/x86: amd-pmc: Move to later in the suspend process
  ACPI / x86: Add support for LPS0 callback handler
  platform/x86: thinkpad_acpi: consistently check fan_get_status return.
  platform/x86: hp-wmi: support omen thermal profile policy v1
  platform/x86: hp-wmi: Changing bios_args.data to be dynamically allocated
  platform/x86: hp-wmi: Fix 0x05 error code reported by several WMI calls
  platform/x86: hp-wmi: Fix SW_TABLET_MODE detection method
  platform/x86: hp-wmi: Fix hp_wmi_read_int() reporting error (0x05)
  platform/x86: amd-pmc: Validate entry into the deepest state on resume
  platform/x86: thinkpad_acpi: Don't use test_bit on an integer
  platform/x86: thinkpad_acpi: Fix compiler warning about uninitialized err variable
  platform/x86: thinkpad_acpi: clean up dytc profile convert
  platform/x86: x86-android-tablets: Depend on EFI and SPI
  platform/x86: amd-pmc: uninitialized variable in amd_pmc_s2d_init()
  platform/x86: intel-uncore-freq: fix uncore_freq_common_init() error codes
  ...
2022-03-25 12:14:39 -07:00
..
obsolete Documentation: ABI: Add ABI file for legacy /proc/i8k interface 2022-02-27 17:03:16 -08:00
removed This was a reasonably active cycle for documentation; this pull includes: 2021-06-28 16:53:05 -07:00
stable for-5.18/block-2022-03-18 2022-03-21 16:48:55 -07:00
testing platform-drivers-x86 for v5.18-1 2022-03-25 12:14:39 -07:00
README docs: ABI: README: specify that files should be ReST compatible 2020-10-30 13:07:01 +01: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.


Note:
   The fields should be use a simple notation, compatible with ReST markup.
   Also, the file **should not** have a top-level index, like::

	===
	foo
	===

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.