Commit 6d37f7e7 authored by Linus Torvalds's avatar Linus Torvalds
Browse files

Merge tag 'acpi-6.9-rc1-2' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm 

Pull more ACPI updates from Rafael Wysocki:
 "These update ACPI documentation and kerneldoc comments.

  Specifics:

   - Add markup to generate links from footnotes in the ACPI enumeration
     document (Chris Packham)

   - Update the handle_eject_request() kerneldoc comment to document the
     arguments of the function and improve kerneldoc comments for ACPI
     suspend and hibernation functions (Yang Li)"

* tag 'acpi-6.9-rc1-2' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm:
  ACPI: PM: Improve kerneldoc comments for suspend and hibernation functions
  ACPI: docs: enumeration: Make footnotes links
  ACPI: Document handle_eject_request() arguments
parents ed302ad5 a873add2

Documentation/firmware-guide/acpi/enumeration.rst

+6 −6
Original line number Diff line number Diff line
@@ -595,7 +595,7 @@ bridges/switches of the board. 


For example, let's assume we have a system with a PCIe serial port, an

Exar XR17V3521, soldered on the main board. This UART chip also includes

16 GPIOs and we want to add the property ``gpio-line-names`` [1] to these pins.

16 GPIOs and we want to add the property ``gpio-line-names`` [1]_ to these pins.

In this case, the ``lspci`` output for this component is::



	07:00.0 Serial controller: Exar Corp. XR17V3521 Dual PCIe UART (rev 03)
@@ -637,7 +637,7 @@ of the chipset bridge (also called "root port") with address:: 
	Bus: 0 - Device: 14 - Function: 1



To find this information, it is necessary to disassemble the BIOS ACPI tables,

in particular the DSDT (see also [2])::

in particular the DSDT (see also [2]_)::



	mkdir ~/tables/

	cd ~/tables/
@@ -667,7 +667,7 @@ device:: 
			}

	... other definitions follow ...



and the _ADR method [3] returns exactly the device/function couple that

and the _ADR method [3]_ returns exactly the device/function couple that

we are looking for. With this information and analyzing the above ``lspci``

output (both the devices list and the devices tree), we can write the following

ACPI description for the Exar PCIe UART, also adding the list of its GPIO line
@@ -724,10 +724,10 @@ created analyzing the position of the Exar UART in the PCI bus topology. 
References

==========



[1] Documentation/firmware-guide/acpi/gpio-properties.rst

.. [1] Documentation/firmware-guide/acpi/gpio-properties.rst



[2] Documentation/admin-guide/acpi/initrd_table_override.rst

.. [2] Documentation/admin-guide/acpi/initrd_table_override.rst



[3] ACPI Specifications, Version 6.3 - Paragraph 6.1.1 _ADR Address)

.. [3] ACPI Specifications, Version 6.3 - Paragraph 6.1.1 _ADR Address)

    https://uefi.org/sites/default/files/resources/ACPI_6_3_May16.pdf,

    referenced 2020-11-18

drivers/acpi/dock.c

+2 −0
Original line number Diff line number Diff line
@@ -380,6 +380,8 @@ static int dock_in_progress(struct dock_station *ds) 


/**

 * handle_eject_request - handle an undock request checking for error conditions

 * @ds: The dock station to undock.

 * @event: The ACPI event number associated with the undock request.

 *

 * Check to make sure the dock device is still present, then undock and

 * hotremove all the devices that may need removing.

drivers/acpi/sleep.c

+14 −10
Original line number Diff line number Diff line
@@ -502,6 +502,7 @@ static void acpi_pm_finish(void) 


/**

 * acpi_pm_start - Start system PM transition.

 * @acpi_state: The target ACPI power state to transition to.

 */

static void acpi_pm_start(u32 acpi_state)

{
@@ -542,6 +543,7 @@ static u32 acpi_suspend_states[] = { 
/**

 * acpi_suspend_begin - Set the target system sleep state to the state

 *	associated with given @pm_state, if supported.

 * @pm_state: The target system power management state.

 */

static int acpi_suspend_begin(suspend_state_t pm_state)

{
@@ -675,6 +677,7 @@ static const struct platform_suspend_ops acpi_suspend_ops = { 
 *	state associated with given @pm_state, if supported, and

 *	execute the _PTS control method.  This function is used if the

 *	pre-ACPI 2.0 suspend ordering has been requested.

 * @pm_state: The target suspend state for the system.

 */

static int acpi_suspend_begin_old(suspend_state_t pm_state)

{
@@ -971,6 +974,7 @@ static const struct platform_hibernation_ops acpi_hibernation_ops = { 
 *	ACPI_STATE_S4 and execute the _PTS control method.  This

 *	function is used if the pre-ACPI 2.0 suspend ordering has been

 *	requested.

 * @stage: The power management event message.

 */

static int acpi_hibernation_begin_old(pm_message_t stage)

{