From 8e0cbf356377fabac47a027dd176cd1cacc5fc01 Mon Sep 17 00:00:00 2001 From: Mark Pearson Date: Tue, 29 Dec 2020 19:18:25 -0500 Subject: Documentation: Add documentation for new platform_profile sysfs attribute On modern systems the platform performance, temperature, fan and other hardware related characteristics are often dynamically configurable. The profile is often automatically adjusted to the load by some automatic-mechanism (which may very well live outside the kernel). These auto platform-adjustment mechanisms often can be configured with one of several 'platform-profiles', with either a bias towards low-power consumption or towards performance (and higher power consumption and thermals). Introduce a new platform_profile sysfs API which offers a generic API for selecting the performance-profile of these automatic-mechanisms. Co-developed-by: Hans de Goede Signed-off-by: Mark Pearson Signed-off-by: Hans de Goede Signed-off-by: Rafael J. Wysocki --- Documentation/ABI/testing/sysfs-platform_profile | 24 +++++++++++++ Documentation/userspace-api/index.rst | 1 + .../userspace-api/sysfs-platform_profile.rst | 42 ++++++++++++++++++++++ 3 files changed, 67 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-platform_profile create mode 100644 Documentation/userspace-api/sysfs-platform_profile.rst (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-platform_profile b/Documentation/ABI/testing/sysfs-platform_profile new file mode 100644 index 000000000000..9d6b89b66cca --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform_profile @@ -0,0 +1,24 @@ +What: /sys/firmware/acpi/platform_profile_choices +Date: October 2020 +Contact: Hans de Goede +Description: This file contains a space-separated list of profiles supported for this device. + + Drivers must use the following standard profile-names: + + ============ ============================================ + low-power Low power consumption + cool Cooler operation + quiet Quieter operation + balanced Balance between low power consumption and performance + performance High performance operation + ============ ============================================ + + Userspace may expect drivers to offer more than one of these + standard profile names. + +What: /sys/firmware/acpi/platform_profile +Date: October 2020 +Contact: Hans de Goede +Description: Reading this file gives the current selected profile for this + device. Writing this file with one of the strings from + platform_profile_choices changes the profile to the new value. diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index acd2cc2a538d..d29b020e5622 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -24,6 +24,7 @@ place where this information is gathered. ioctl/index iommu media/index + sysfs-platform_profile .. only:: subproject and html diff --git a/Documentation/userspace-api/sysfs-platform_profile.rst b/Documentation/userspace-api/sysfs-platform_profile.rst new file mode 100644 index 000000000000..c33a71263d9e --- /dev/null +++ b/Documentation/userspace-api/sysfs-platform_profile.rst @@ -0,0 +1,42 @@ +===================================================================== +Platform Profile Selection (e.g. /sys/firmware/acpi/platform_profile) +===================================================================== + +On modern systems the platform performance, temperature, fan and other +hardware related characteristics are often dynamically configurable. The +platform configuration is often automatically adjusted to the current +conditions by some automatic mechanism (which may very well live outside +the kernel). + +These auto platform adjustment mechanisms often can be configured with +one of several platform profiles, with either a bias towards low power +operation or towards performance. + +The purpose of the platform_profile attribute is to offer a generic sysfs +API for selecting the platform profile of these automatic mechanisms. + +Note that this API is only for selecting the platform profile, it is +NOT a goal of this API to allow monitoring the resulting performance +characteristics. Monitoring performance is best done with device/vendor +specific tools such as e.g. turbostat. + +Specifically when selecting a high performance profile the actual achieved +performance may be limited by various factors such as: the heat generated +by other components, room temperature, free air flow at the bottom of a +laptop, etc. It is explicitly NOT a goal of this API to let userspace know +about any sub-optimal conditions which are impeding reaching the requested +performance level. + +Since numbers on their own cannot represent the multiple variables that a +profile will adjust (power consumption, heat generation, etc) this API +uses strings to describe the various profiles. To make sure that userspace +gets a consistent experience the sysfs-platform_profile ABI document defines +a fixed set of profile names. Drivers *must* map their internal profile +representation onto this fixed set. + +If there is no good match when mapping then a new profile name may be +added. Drivers which wish to introduce new profile names must: + + 1. Explain why the existing profile names canot be used. + 2. Add the new profile name, along with a clear description of the + expected behaviour, to the sysfs-platform_profile ABI documentation. -- cgit v1.2.3 From 731e97e0769805cdebfd7d2b19a7d3f6abcace09 Mon Sep 17 00:00:00 2001 From: Flavio Suligoi Date: Fri, 8 Jan 2021 16:24:47 +0100 Subject: Documentation: ACPI: add new rule for gpio-line-names The gpio-line-names lists must respect some rules. This patch adds a new rule in documentation, to avoid the use of duplicate names in the same gpiochip. Signed-off-by: Flavio Suligoi Reviewed-by: Andy Shevchenko Signed-off-by: Rafael J. Wysocki --- Documentation/firmware-guide/acpi/gpio-properties.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/firmware-guide/acpi/gpio-properties.rst b/Documentation/firmware-guide/acpi/gpio-properties.rst index b36aa3e743d8..4e264c16ddff 100644 --- a/Documentation/firmware-guide/acpi/gpio-properties.rst +++ b/Documentation/firmware-guide/acpi/gpio-properties.rst @@ -146,6 +146,7 @@ following rules (see also the examples): other words, it is not mandatory to fill all the GPIO lines - empty names are allowed (two quotation marks ``""`` correspond to an empty name) + - names inside one GPIO controller/expander must be unique Example of a GPIO controller of 16 lines, with an incomplete list with two empty names:: -- cgit v1.2.3 From c56fd5ead29b6ad6625af632a91a231129027185 Mon Sep 17 00:00:00 2001 From: "Rafael J. Wysocki" Date: Wed, 20 Jan 2021 19:58:18 +0100 Subject: ACPI: PM: Clean up printing messages Replace the remaining ACPI_DEBUG_PRINT() instances in device_pm.c with dev_dbg() invocations, drop the _COMPONENT and ACPI_MODULE_NAME() definitions that are not used any more, and drop the no longer needed ACPI_POWER_COMPONENT definition from the headers and documentation. Signed-off-by: Rafael J. Wysocki --- Documentation/firmware-guide/acpi/debug.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/firmware-guide/acpi/debug.rst b/Documentation/firmware-guide/acpi/debug.rst index 1a152dd1d765..73f88a27f12b 100644 --- a/Documentation/firmware-guide/acpi/debug.rst +++ b/Documentation/firmware-guide/acpi/debug.rst @@ -59,7 +59,6 @@ shows the supported mask values, currently these:: ACPI_SBS_COMPONENT 0x00100000 ACPI_FAN_COMPONENT 0x00200000 ACPI_PCI_COMPONENT 0x00400000 - ACPI_POWER_COMPONENT 0x00800000 ACPI_CONTAINER_COMPONENT 0x01000000 ACPI_SYSTEM_COMPONENT 0x02000000 ACPI_THERMAL_COMPONENT 0x04000000 -- cgit v1.2.3 From 12bfee94c23063142e8c370c651ba33482388a51 Mon Sep 17 00:00:00 2001 From: "Rafael J. Wysocki" Date: Wed, 20 Jan 2021 20:01:18 +0100 Subject: ACPI: bus: Drop ACPI_BUS_COMPONENT which is not used any more After dropping all of the code using ACPI_BUS_COMPONENT drop it too and modify the example in the documentation using it. Signed-off-by: Rafael J. Wysocki --- Documentation/firmware-guide/acpi/debug.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/firmware-guide/acpi/debug.rst b/Documentation/firmware-guide/acpi/debug.rst index 73f88a27f12b..c7bad74c6ff7 100644 --- a/Documentation/firmware-guide/acpi/debug.rst +++ b/Documentation/firmware-guide/acpi/debug.rst @@ -52,7 +52,6 @@ shows the supported mask values, currently these:: ACPI_CA_DISASSEMBLER 0x00000800 ACPI_COMPILER 0x00001000 ACPI_TOOLS 0x00002000 - ACPI_BUS_COMPONENT 0x00010000 ACPI_AC_COMPONENT 0x00020000 ACPI_BATTERY_COMPONENT 0x00040000 ACPI_BUTTON_COMPONENT 0x00080000 @@ -117,15 +116,15 @@ currently these:: Examples ======== -For example, drivers/acpi/bus.c contains this:: +For example, drivers/acpi/acpica/evxfevnt.c contains this:: - #define _COMPONENT ACPI_BUS_COMPONENT + #define _COMPONENT ACPI_EVENTS ... - ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Device insertion detected\n")); + ACPI_DEBUG_PRINT((ACPI_DB_INIT, "ACPI mode disabled\n")); -To turn on this message, set the ACPI_BUS_COMPONENT bit in acpi.debug_layer -and the ACPI_LV_INFO bit in acpi.debug_level. (The ACPI_DEBUG_PRINT -statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO +To turn on this message, set the ACPI_EVENTS bit in acpi.debug_layer +and the ACPI_LV_INIT bit in acpi.debug_level. (The ACPI_DEBUG_PRINT +statement uses ACPI_DB_INIT, which is a macro based on the ACPI_LV_INIT definition.) Enable all AML "Debug" output (stores to the Debug object while interpreting -- cgit v1.2.3 From 2249ff344467b5ab4da31c1e0873c56521aa345b Mon Sep 17 00:00:00 2001 From: "Rafael J. Wysocki" Date: Wed, 3 Feb 2021 19:43:17 +0100 Subject: ACPI: AC: Clean up printing messages Replace the ACPI_DEBUG_PRINT() and ACPI_EXCEPTION() instances in ac.c with acpi_handle_debug() and acpi_handle_info() calls, respectively, which among other things causes the excessive log level of the messages previously printed via ACPI_EXCEPTION() to be increased. Drop the _COMPONENT and ACPI_MODULE_NAME() definitions that are not used any more, drop the no longer needed ACPI_AC_COMPONENT definition from the headers and update the documentation accordingly. While at it, replace the direct printk() invocation with pr_info(), add a pr_fmt() definition to ac.c and drop the unneeded PREFIX symbol definition from there. Signed-off-by: Rafael J. Wysocki Reviewed-by: Hanjun Guo Reviewed-by: Hans de Goede --- Documentation/firmware-guide/acpi/debug.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/firmware-guide/acpi/debug.rst b/Documentation/firmware-guide/acpi/debug.rst index c7bad74c6ff7..cb61b1ab7276 100644 --- a/Documentation/firmware-guide/acpi/debug.rst +++ b/Documentation/firmware-guide/acpi/debug.rst @@ -52,7 +52,6 @@ shows the supported mask values, currently these:: ACPI_CA_DISASSEMBLER 0x00000800 ACPI_COMPILER 0x00001000 ACPI_TOOLS 0x00002000 - ACPI_AC_COMPONENT 0x00020000 ACPI_BATTERY_COMPONENT 0x00040000 ACPI_BUTTON_COMPONENT 0x00080000 ACPI_SBS_COMPONENT 0x00100000 -- cgit v1.2.3 From bd8c5d1ee37ff4726367128ccdfd83300ee4e3d3 Mon Sep 17 00:00:00 2001 From: "Rafael J. Wysocki" Date: Wed, 3 Feb 2021 19:44:57 +0100 Subject: ACPI: battery: Clean up printing messages Replace the ACPI_DEBUG_PRINT() and ACPI_EXCEPTION() instances in battery.c with acpi_handle_debug() and acpi_handle_info() calls, respectively, which among other things causes the excessive log level of the messages previously printed via ACPI_EXCEPTION() to be increased. Drop the _COMPONENT and ACPI_MODULE_NAME() definitions that are not used any more, drop the no longer needed ACPI_BATTERY_COMPONENT definition from the headers and update the documentation accordingly. While at it, update the pr_fmt() definition and drop the unneeded PREFIX sybmbol definition from battery.c. Also adapt the existing pr_info() calls to the new pr_fmt() definition. Signed-off-by: Rafael J. Wysocki Reviewed-by: Hanjun Guo Reviewed-by: Hans de Goede --- Documentation/firmware-guide/acpi/debug.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/firmware-guide/acpi/debug.rst b/Documentation/firmware-guide/acpi/debug.rst index cb61b1ab7276..60d877913da3 100644 --- a/Documentation/firmware-guide/acpi/debug.rst +++ b/Documentation/firmware-guide/acpi/debug.rst @@ -52,7 +52,6 @@ shows the supported mask values, currently these:: ACPI_CA_DISASSEMBLER 0x00000800 ACPI_COMPILER 0x00001000 ACPI_TOOLS 0x00002000 - ACPI_BATTERY_COMPONENT 0x00040000 ACPI_BUTTON_COMPONENT 0x00080000 ACPI_SBS_COMPONENT 0x00100000 ACPI_FAN_COMPONENT 0x00200000 -- cgit v1.2.3 From 411e3216d4ee7e3c25c365b0d09e18f7798d705a Mon Sep 17 00:00:00 2001 From: "Rafael J. Wysocki" Date: Wed, 3 Feb 2021 19:46:14 +0100 Subject: ACPI: button: Clean up printing messages Replace the ACPI_DEBUG_PRINT() instance in button.c with an acpi_handle_debug() call, drop the _COMPONENT and ACPI_MODULE_NAME() definitions that are not used any more, drop the no longer needed ACPI_BUTTON_COMPONENT definition from the headers and update the documentation accordingly. While at it, replace the direct printk() invocations with pr_info() (that changes the excessive log level for some of them too) and drop the unneeded PREFIX sybmbol definition from battery.c. Signed-off-by: Rafael J. Wysocki Reviewed-by: Hanjun Guo Reviewed-by: Hans de Goede --- Documentation/firmware-guide/acpi/debug.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/firmware-guide/acpi/debug.rst b/Documentation/firmware-guide/acpi/debug.rst index 60d877913da3..67a5ad75a52e 100644 --- a/Documentation/firmware-guide/acpi/debug.rst +++ b/Documentation/firmware-guide/acpi/debug.rst @@ -52,7 +52,6 @@ shows the supported mask values, currently these:: ACPI_CA_DISASSEMBLER 0x00000800 ACPI_COMPILER 0x00001000 ACPI_TOOLS 0x00002000 - ACPI_BUTTON_COMPONENT 0x00080000 ACPI_SBS_COMPONENT 0x00100000 ACPI_FAN_COMPONENT 0x00200000 ACPI_PCI_COMPONENT 0x00400000 -- cgit v1.2.3 From 2924d2f837788bb0efaa79ece1e5b9e57928834b Mon Sep 17 00:00:00 2001 From: "Rafael J. Wysocki" Date: Wed, 3 Feb 2021 19:48:33 +0100 Subject: ACPI: video: Clean up printing messages Replace the ACPI_DEBUG_PRINT() instances in acpi_video.c with acpi_handle_debug() calls and the ACPI_EXCEPTION()/ACPI_ERROR()/ ACPI_WARNING() instances in there with acpi_handle_info() calls, which among other things causes the excessive log levels of those messages to be increased. Drop the _COMPONENT and ACPI_MODULE_NAME() definitions that are not used any more from acpi_video.c, drop the no longer needed ACPI_VIDEO_COMPONENT definition from the headers and update the documentation accordingly. While at it, add a pr_fmt() definition to acpi_video.c, replace the direct printk() invocations in there with acpi_handle_info() or pr_info() (and reduce the excessive log level where applicable) and drop the PREFIX sybmbol definition which is not necessary any more from acpi_video.c. Also make unrelated janitorial changes to fix up white space and use ACPI_FAILURE() instead of negating ACPI_SUCCESS(). Signed-off-by: Rafael J. Wysocki Reviewed-by: Hanjun Guo Reviewed-by: Hans de Goede --- Documentation/firmware-guide/acpi/debug.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/firmware-guide/acpi/debug.rst b/Documentation/firmware-guide/acpi/debug.rst index 67a5ad75a52e..761fae76bcce 100644 --- a/Documentation/firmware-guide/acpi/debug.rst +++ b/Documentation/firmware-guide/acpi/debug.rst @@ -59,7 +59,6 @@ shows the supported mask values, currently these:: ACPI_SYSTEM_COMPONENT 0x02000000 ACPI_THERMAL_COMPONENT 0x04000000 ACPI_MEMORY_DEVICE_COMPONENT 0x08000000 - ACPI_VIDEO_COMPONENT 0x10000000 ACPI_PROCESSOR_COMPONENT 0x20000000 debug_level -- cgit v1.2.3 From f86b15a1e6541446a4a5f69bcc211348238db97f Mon Sep 17 00:00:00 2001 From: "Rafael J. Wysocki" Date: Wed, 3 Feb 2021 19:49:21 +0100 Subject: ACPI: thermal: Clean up printing messages Replace the ACPI_DEBUG_PRINT() instances in thermal.c with acpi_handle_debug() calls and modify the ACPI_THERMAL_TRIPS_EXCEPTION() macro in there to use acpi_handle_info() internally, which among other things causes the excessive log level of the messages printed by it to be increased. Drop the _COMPONENT and ACPI_MODULE_NAME() definitions that are not used any more from thermal.c, drop the no longer needed ACPI_THERMAL_COMPONENT definition from the headers and update the documentation accordingly. While at it, add a pr_fmt() definition to thermal.c, drop the PREFIX definition from there and replace some pr_warn() calls with pr_info() or acpi_handle_info() to reduce the excessive log level and (in the latter case) facilitate easier identification of the message source. Signed-off-by: Rafael J. Wysocki Reviewed-by: Hanjun Guo Reviewed-by: Hans de Goede --- Documentation/firmware-guide/acpi/debug.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/firmware-guide/acpi/debug.rst b/Documentation/firmware-guide/acpi/debug.rst index 761fae76bcce..03cd4e25fc45 100644 --- a/Documentation/firmware-guide/acpi/debug.rst +++ b/Documentation/firmware-guide/acpi/debug.rst @@ -57,7 +57,6 @@ shows the supported mask values, currently these:: ACPI_PCI_COMPONENT 0x00400000 ACPI_CONTAINER_COMPONENT 0x01000000 ACPI_SYSTEM_COMPONENT 0x02000000 - ACPI_THERMAL_COMPONENT 0x04000000 ACPI_MEMORY_DEVICE_COMPONENT 0x08000000 ACPI_PROCESSOR_COMPONENT 0x20000000 -- cgit v1.2.3