From 0a500b810e4aeaadbfff71fa5a0be57d01eb8926 Mon Sep 17 00:00:00 2001 From: Yang Li Date: Fri, 8 Mar 2024 15:32:14 +0800 Subject: [PATCH 1/3] ACPI: Document handle_eject_request() arguments Add argument descriptions to the handle_eject_request() kerneldoc comment. Signed-off-by: Yang Li Acked-by: Randy Dunlap [ rjw: Subject and changelog edits ] Signed-off-by: Rafael J. Wysocki --- drivers/acpi/dock.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/drivers/acpi/dock.c b/drivers/acpi/dock.c index a89bdbe00184..a7c00ef78086 100644 --- a/drivers/acpi/dock.c +++ b/drivers/acpi/dock.c @@ -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. From e1c69f348df4cd33f25c248a7a907cb0457f0ee0 Mon Sep 17 00:00:00 2001 From: Chris Packham Date: Thu, 14 Mar 2024 10:40:38 +1300 Subject: [PATCH 2/3] ACPI: docs: enumeration: Make footnotes links Update the numeric footnotes so that they are rendered as hyperlinks in the html output. Signed-off-by: Chris Packham Signed-off-by: Rafael J. Wysocki --- Documentation/firmware-guide/acpi/enumeration.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index d79f69390991..0165b09c0957 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -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 From d7ef570ae0bfd2375a7e7fe468fd6b1b306272c1 Mon Sep 17 00:00:00 2001 From: Yang Li Date: Fri, 15 Mar 2024 08:37:53 +0800 Subject: [PATCH 3/3] ACPI: PM: Improve kerneldoc comments for suspend and hibernation functions This patch enhances the documentation for the ACPI power management functions related to system suspend and hibernation. This includes the use of kernel-doc style comments which provide developers with clearer guidance on the usage and expectations of these functions. Signed-off-by: Yang Li Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap [ rjw: Subject edits ] Signed-off-by: Rafael J. Wysocki --- drivers/acpi/sleep.c | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/drivers/acpi/sleep.c b/drivers/acpi/sleep.c index 808484d11209..daf351007b69 100644 --- a/drivers/acpi/sleep.c +++ b/drivers/acpi/sleep.c @@ -514,6 +514,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) { @@ -552,8 +553,9 @@ static u32 acpi_suspend_states[] = { }; /** - * acpi_suspend_begin - Set the target system sleep state to the state - * associated with given @pm_state, if supported. + * 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) { @@ -683,10 +685,11 @@ static const struct platform_suspend_ops acpi_suspend_ops = { }; /** - * acpi_suspend_begin_old - Set the target system sleep state to the - * 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. + * acpi_suspend_begin_old - Set the target system sleep state to the + * 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) { @@ -979,10 +982,11 @@ static const struct platform_hibernation_ops acpi_hibernation_ops = { }; /** - * acpi_hibernation_begin_old - Set the target system sleep state to - * ACPI_STATE_S4 and execute the _PTS control method. This - * function is used if the pre-ACPI 2.0 suspend ordering has been - * requested. + * acpi_hibernation_begin_old - Set the target system sleep state to + * 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) {