kernel_optimize_test/Documentation/ABI
Linus Torvalds 07c455ee22 platform-drivers-x86 for v4.15-1
For this cycle we have quite an update for the Dell SMBIOS driver
 including WMI work to provide an interface for SMBIOS tokens via sysfs
 and WMI support for 2017+ Dell laptop models. SMM dispatcher code is
 split into a separate driver followed by a new WMI dispatcher.
 The latter provides a character device interface to user space.
 
 The pull request contains a merge of immutable branch from Wolfram Sang
 in order to apply a dependent fix to the Intel CherryTrail Battery
 Management driver.
 
 Other Intel drivers got a lot of cleanups. The Turbo Boost Max 3.0
 support is added for Intel Skylake.
 
 Peaq WMI hotkeys driver gets its own maintainer and white list of
 supported models.
 
 Silead DMI is expanded to support few additional platforms.
 
 Tablet mode via GMMS ACPI method is added to support some ThinkPad
 tablets.
 
 Two commits appear here which were previously merged during the
 v4.14-rcX cycle:
 
 - d7ca5ebf24 platform/x86: intel_pmc_ipc: Use devm_* calls in driver probe function
 - e3075fd6f8 platform/x86: intel_pmc_ipc: Use spin_lock to protect GCR updates
 
 Add driver to force WMI Thunderbolt controller power status:
  - Add driver to force WMI Thunderbolt controller power status
 
 asus-wmi:
  -  Add lightbar led support
 
 dell-laptop:
  -  Allocate buffer before rfkill use
 
 dell-smbios:
  -  fix string overflow
  -  Add filtering support
  -  Introduce dispatcher for SMM calls
  -  Add a sysfs interface for SMBIOS tokens
  -  only run if proper oem string is detected
  -  Prefix class/select with cmd_
  -  Add pr_fmt definition to driver
 
 dell-smbios-smm:
  -  test for WSMT
 
 dell-smbios-wmi:
  -  release mutex lock on WMI call failure
  -  introduce userspace interface
  -  Add new WMI dispatcher driver
 
 dell-smo8800:
  -  remove redundant assignments to byte_data
 
 dell-wmi:
  -  don't check length returned
  -  clean up wmi descriptor check
  -  increase severity of some failures
  -  Do not match on descriptor GUID modalias
  -  Label driver as handling notifications
 
 dell-*wmi*:
  -  Relay failed initial probe to dependent drivers
 
 dell-wmi-descriptor:
  -  check if memory was allocated
  -  split WMI descriptor into it's own driver
 
 fujitsu-laptop:
  -  Fix radio LED detection
  -  Don't oops when FUJ02E3 is not presnt
 
 hp_accel:
  -  Add quirk for HP ProBook 440 G4
 
 hp-wmi:
  -  Fix tablet mode detection for convertibles
 
 ideapad-laptop:
  -  Add Lenovo Yoga 920-13IKB to no_hw_rfkill dmi list
 
 intel_cht_int33fe:
  -  Update fusb302 type string, add properties
  -  make a couple of local functions static
  -  Work around BIOS bug on some devices
 
 intel-hid:
  -  Power button suspend on Dell Latitude 7275
 
 intel_ips:
  -  Convert timers to use timer_setup()
  -  Remove FSF address from GPL notice
  -  Remove unneeded fields and label
  -  Keep pointer to struct device
  -  Use PCI_VDEVICE() macro
  -  Switch to new PCI IRQ allocation API
  -  Simplify error handling via devres API
 
 intel_pmc_ipc:
  -  Revert Use MFD framework to create dependent devices
  -  Use MFD framework to create dependent devices
  -  Use spin_lock to protect GCR updates
  -  Use devm_* calls in driver probe function
 
 intel_punit_ipc:
  -  Fix resource ioremap warning
 
 intel_telemetry:
  -  Remove useless default in Kconfig
  -  Add needed inclusion
  -  cleanup redundant headers
  -  Fix typos
  -  Fix load failure info
 
 intel_telemetry_debugfs:
  -  Use standard ARRAY_SIZE() macro
 
 intel_turbo_max_3:
  -  Add Skylake platform
 
 intel-wmi-thunderbolt:
  -  Silence error cases
 
 MAINTAINERS:
  -  Add entry for the PEAQ WMI hotkeys driver
 
 mlx-platform:
  -  make a couple of structures static
 
 peaq_wmi:
  -  Fix missing terminating entry for peaq_dmi_table
 
 peaq-wmi:
  -  Remove unnecessary checks from peaq_wmi_exit
  -  Add DMI check before binding to the WMI interface
  -  Revert Blacklist Lenovo ideapad 700-15ISK
  -  Blacklist Lenovo ideapad 700-15ISK
 
 silead_dmi:
  -  Add silead, home-button property to some tablets
  -  Add entry for the Digma e200 tablet
  -  Fix GP-electronic T701 entry
  -  Add entry for the Chuwi Hi8 Pro tablet
 
 sony-laptop:
  -  Drop variable assignment in sony_nc_setup_rfkill()
  -  Fix error handling in sony_nc_setup_rfkill()
 
 thinkpad_acpi:
  -  Implement tablet mode using GMMS method
 
 tools/wmi:
  -  add a sample for dell smbios communication over WMI
 
 wmi:
  -  release mutex on module acquistion failure
  -  create userspace interface for drivers
  -  Don't allow drivers to get each other's GUIDs
  -  Add new method wmidev_evaluate_method
  -  Destroy on cleanup rather than unregister
  -  Cleanup exit routine in reverse order of init
  -  Sort include list
 -----BEGIN PGP SIGNATURE-----
 
 iQIzBAABCgAdFiEEhiZOUlnC9oKN3n3AmT3/83c5Sy0FAloQcs0ACgkQmT3/83c5
 Sy2agQ//WJirmlqR4WMSDynq0w/rKomx7qMZvabbIxFc7n5beCUrlc61lt4x/cPN
 0HrdkNcYvkW21j8q/Lk5RDlK45JLZLgtDb1rIGjx8Pkf+EXyKwNb4UtqaZuwZRN6
 nVnSGAdShF6f4OqVQU+ZuRr2nQvBlK4OyopKuRaq0kuejJjMLq1sc7VNidvb9zdj
 w4zfhh8RQ2KV3NK8g0k/uQu573Y+tCDUQvxQj5YIgC4RWbv4ZTuZD1Hbjc3Vdy9+
 z0RvrUBCikM0CTqVyXn/ncgiMnAj6oeLdB76F1dlaIaAH/WtisEWr3hLWHskdJwW
 N+qGBB0K72gUHwr4Ck4x2s/S76XeiFYD0BeHL3ODn6ZlKoh7gV2NVwYFDNQHd+uc
 MXN9Xzs3lRkiDFyoXbtBG0wZRn2rS1rhGSYDYQUKg8Qf7MirwEVdYA0CZKeXAA78
 2V29FNdvUmWiL/ZiA/2peeuUTWgPdzENDLHXzE/jOCGBS2/pL4znYv2ZSJ+HIeyW
 oCVMxasSI3pMLxCU8KxgA1QwrbDoiFTYYXCa1Ighq9o2ZEoy7Ub1XmpBB9HKHby7
 K6zQcCYcf+SyscIqvu50ZImZ8nt5FnIdPSrTOX/FMM0Niv42mfKwD+UniG+P5K1z
 OLCIEm74NE9jRjzxuW5E1DSo56gJHUbxxy1rOFzgJnGQ+CAVXKo=
 =upqs
 -----END PGP SIGNATURE-----

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

Pull x86 platform driver updates from Andy Shevchenko:
 "Here is the collected material against Platform Drivers x86 subsystem.
  It's rather bit busy cycle for PDx86, mostly due to Dell SMBIOS driver
  activity

  For this cycle we have quite an update for the Dell SMBIOS driver
  including WMI work to provide an interface for SMBIOS tokens via sysfs
  and WMI support for 2017+ Dell laptop models. SMM dispatcher code is
  split into a separate driver followed by a new WMI dispatcher. The
  latter provides a character device interface to user space.

  The git history also contains a merge of immutable branch from Wolfram
  Sang in order to apply a dependent fix to the Intel CherryTrail
  Battery Management driver.

  Other Intel drivers got a lot of cleanups. The Turbo Boost Max 3.0
  support is added for Intel Skylake.

  Peaq WMI hotkeys driver gets its own maintainer and white list of
  supported models.

  Silead DMI is expanded to support few additional platforms.

  Tablet mode via GMMS ACPI method is added to support some ThinkPad
  tablets.

  new driver:
   - Add driver to force WMI Thunderbolt controller power status

  asus-wmi:
   -  Add lightbar led support

  dell-laptop:
   -  Allocate buffer before rfkill use

  dell-smbios:
   -  fix string overflow
   -  Add filtering support
   -  Introduce dispatcher for SMM calls
   -  Add a sysfs interface for SMBIOS tokens
   -  only run if proper oem string is detected
   -  Prefix class/select with cmd_
   -  Add pr_fmt definition to driver

  dell-smbios-smm:
   -  test for WSMT

  dell-smbios-wmi:
   -  release mutex lock on WMI call failure
   -  introduce userspace interface
   -  Add new WMI dispatcher driver

  dell-smo8800:
   -  remove redundant assignments to byte_data

  dell-wmi:
   -  don't check length returned
   -  clean up wmi descriptor check
   -  increase severity of some failures
   -  Do not match on descriptor GUID modalias
   -  Label driver as handling notifications

  dell-*wmi*:
   -  Relay failed initial probe to dependent drivers

  dell-wmi-descriptor:
   -  check if memory was allocated
   -  split WMI descriptor into it's own driver

  fujitsu-laptop:
   -  Fix radio LED detection
   -  Don't oops when FUJ02E3 is not presnt

  hp_accel:
   -  Add quirk for HP ProBook 440 G4

  hp-wmi:
   -  Fix tablet mode detection for convertibles

  ideapad-laptop:
   -  Add Lenovo Yoga 920-13IKB to no_hw_rfkill dmi list

  intel_cht_int33fe:
   -  Update fusb302 type string, add properties
   -  make a couple of local functions static
   -  Work around BIOS bug on some devices

  intel-hid:
   -  Power button suspend on Dell Latitude 7275

  intel_ips:
   -  Convert timers to use timer_setup()
   -  Remove FSF address from GPL notice
   -  Remove unneeded fields and label
   -  Keep pointer to struct device
   -  Use PCI_VDEVICE() macro
   -  Switch to new PCI IRQ allocation API
   -  Simplify error handling via devres API

  intel_pmc_ipc:
   -  Revert Use MFD framework to create dependent devices
   -  Use MFD framework to create dependent devices
   -  Use spin_lock to protect GCR updates
   -  Use devm_* calls in driver probe function

  intel_punit_ipc:
   -  Fix resource ioremap warning

  intel_telemetry:
   -  Remove useless default in Kconfig
   -  Add needed inclusion
   -  cleanup redundant headers
   -  Fix typos
   -  Fix load failure info

  intel_telemetry_debugfs:
   -  Use standard ARRAY_SIZE() macro

  intel_turbo_max_3:
   -  Add Skylake platform

  intel-wmi-thunderbolt:
   -  Silence error cases

  mlx-platform:
   -  make a couple of structures static

  peaq_wmi:
   -  Fix missing terminating entry for peaq_dmi_table

  peaq-wmi:
   -  Remove unnecessary checks from peaq_wmi_exit
   -  Add DMI check before binding to the WMI interface
   -  Revert Blacklist Lenovo ideapad 700-15ISK
   -  Blacklist Lenovo ideapad 700-15ISK

  silead_dmi:
   -  Add silead, home-button property to some tablets
   -  Add entry for the Digma e200 tablet
   -  Fix GP-electronic T701 entry
   -  Add entry for the Chuwi Hi8 Pro tablet

  sony-laptop:
   -  Drop variable assignment in sony_nc_setup_rfkill()
   -  Fix error handling in sony_nc_setup_rfkill()

  thinkpad_acpi:
   -  Implement tablet mode using GMMS method

  tools/wmi:
   -  add a sample for dell smbios communication over WMI

  wmi:
   -  release mutex on module acquistion failure
   -  create userspace interface for drivers
   -  Don't allow drivers to get each other's GUIDs
   -  Add new method wmidev_evaluate_method
   -  Destroy on cleanup rather than unregister
   -  Cleanup exit routine in reverse order of init
   -  Sort include list"

* tag 'platform-drivers-x86-v4.15-1' of git://git.infradead.org/linux-platform-drivers-x86: (74 commits)
  platform/x86: silead_dmi: Add silead, home-button property to some tablets
  platform/x86: dell-laptop: Allocate buffer before rfkill use
  platform/x86: dell-*wmi*: Relay failed initial probe to dependent drivers
  platform/x86: dell-wmi-descriptor: check if memory was allocated
  platform/x86: Revert intel_pmc_ipc: Use MFD framework to create dependent devices
  platform/x86: dell-smbios-wmi: release mutex lock on WMI call failure
  platform/x86: wmi: release mutex on module acquistion failure
  platform/x86: dell-smbios: fix string overflow
  platform/x86: intel_pmc_ipc: Use MFD framework to create dependent devices
  platform/x86: intel_punit_ipc: Fix resource ioremap warning
  platform/x86: dell-smo8800: remove redundant assignments to byte_data
  platform/x86: hp-wmi: Fix tablet mode detection for convertibles
  platform/x86: intel_ips: Convert timers to use timer_setup()
  platform/x86: sony-laptop: Drop variable assignment in sony_nc_setup_rfkill()
  platform/x86: sony-laptop: Fix error handling in sony_nc_setup_rfkill()
  tools/wmi: add a sample for dell smbios communication over WMI
  platform/x86: dell-smbios-wmi: introduce userspace interface
  platform/x86: wmi: create userspace interface for drivers
  platform/x86: dell-smbios: Add filtering support
  platform/x86: dell-smbios-smm: test for WSMT
  ...
2017-11-18 10:26:57 -08:00
..
obsolete This is the bulk of GPIO changes for the v4.15 kernel cycle: 2017-11-14 17:23:44 -08:00
removed rfkill: Remove obsolete "claim" sysfs interface 2016-02-24 09:04:24 +01:00
stable Char/Misc patches for 4.15-rc1 2017-11-16 09:10:59 -08:00
testing platform-drivers-x86 for v4.15-1 2017-11-18 10:26:57 -08: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.