Documentation: Add documentation for new platform_profile sysfs attribute
Subsystems (3)
PATCH v6 1/3 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.
---
Changes in v2:
- updated to rst format
Changes in v3, v4, v5
- version bump along with rest of patch series
Changes in v6:
- Split sysfs-platform_profile.rs into ABI text and then admin guide in userspace-api section. Hope this is correct - I'm guessing a bit.
.../ABI/testing/sysfs-platform_profile | 24 +++++++++++ Documentation/userspace-api/index.rst | 1 + .../userspace-api/sysfs-platform_profile.rst | 43 +++++++++++++++++++ 3 files changed, 68 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-platform_profile create mode 100644 Documentation/userspace-api/sysfs-platform_profile.rst
Documentation/ABI/testing/sysfs-platform_profile new file +24 -0
@@ -0,0 +1,24 @@ +What: /sys/firmware/acpi/platform_profile_choices +Date: October 2020 +Contact: Hans de Goede <[email protected]> +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 <[email protected]> +Description: Reading this file gives the current selected profile for this + device. Writing this file with one of the strings from + available_profiles changes the profile to the new value.
Documentation/userspace-api/index.rst +1 -0
@@ -24,6 +24,7 @@ place where this information is gathered. ioctl/index iommu media/index + sysfs-platform_profile .. only:: subproject and html
Documentation/userspace-api/sysfs-platform_profile.rst new file +43 -0
43 lines not on this page · raw message
Signature · 1 line
2.28.0
PATCH v6 2/3 ACPI: platform-profile: Add platform profile support
This is the initial implementation of the platform-profile feature. It provides the details discussed and outlined in the sysfs-platform_profile document.
Many modern systems have the ability to modify the operating profile to control aspects like fan speed, temperature and power levels. This module provides a common sysfs interface that platform modules can register against to control their individual profile options.
---
Changes in v2:
Address (hopefully) all recommendations from review including:
- reorder includes list alphabetically
- make globals statics and use const as required
- change profile name scanning to use full string
- clean up profile name lists to remove unwanted additions
- use sysfs_emit and sysfs_emit_at appropriately (much nicer!)
- improve error handling. Return errors to user in all cases and use better error codes where appropriate (ENOOPSUPP)
- clean up sysfs output for better readability
- formatting fixes where needed
- improve structure and enum names to be clearer
- remove cur_profile field from structure. It is now local to the actual platform driver file (patch 3 in series)
- improve checking so if future profile options are added profile_names will be updated as well.
- move CONFIG option next to ACPI_THERMAL as it seemed slightly related
- removed MAINTAINERS update as not appropriate (note warning message is seen when running checkpatch)
Changes in v3:
- Add missed platform_profile.h file
Changes in v4:
- Clean up duplicate entry in Kconfig file
- Add linux/bits.h to include list
- Remove unnecessary items from include list
- Make cur_profile const
- Clean up comments
- formatting clean-ups
- add checking of profile return value to show function
- add checking to store to see if it's a supported profile
- revert ENOTSUPP change in store function
- improved error checking in profile registration
- improved profile naming (now platform_profile_*)
Changes in v5:
- correct 'balance' to 'balanced' to be consistent with documentation
- add WARN_ON when checking profile index in show function
- switch mutex_lock_interruptible back to mutex_lock where appropriate
- add 'platform_profile_last' as final entry in profile entry. Update implementation to use this appropriately
- Use BITS_TO_LONG and appropriate access functions for choices field
- Correct error handling as recommended
- Sanity check profile fields on registration
- Remove unnecessary init and exit functions
Changed in v6:
- Change default build option to 'm' and clean in formating in Kconfig
- Change enums to be capitalised as requested
- Rename unregister function to remove
drivers/acpi/Kconfig | 17 +++ drivers/acpi/Makefile | 1 + drivers/acpi/platform_profile.c | 181 +++++++++++++++++++++++++++++++ include/linux/platform_profile.h | 39 +++++++ 4 files changed, 238 insertions(+) create mode 100644 drivers/acpi/platform_profile.c create mode 100644 include/linux/platform_profile.h
drivers/acpi/Kconfig +17 -0
@@ -326,6 +326,23 @@ config ACPI_THERMAL To compile this driver as a module, choose M here: the module will be called thermal. +config ACPI_PLATFORM_PROFILE + tristate "ACPI Platform Profile Driver" + default m + help + This driver adds support for platform-profiles on platforms that + support it. + + Platform-profiles can be used to control the platform behaviour. For + example whether to operate in a lower power mode, in a higher + power performance mode or between the two. + + This driver provides the sysfs interface and is used as the registration + point for platform specific drivers. + + Which profiles are supported is determined on a per-platform basis and + should be obtained from the platform specific driver. + config ACPI_CUSTOM_DSDT_FILE string "Custom DSDT Table file to include" default ""
drivers/acpi/Makefile +1 -0
@@ -78,6 +78,7 @@ obj-$(CONFIG_ACPI_PCI_SLOT) += pci_slot.o obj-$(CONFIG_ACPI_PROCESSOR) += processor.o obj-$(CONFIG_ACPI) += container.o obj-$(CONFIG_ACPI_THERMAL) += thermal.o +obj-$(CONFIG_ACPI_PLATFORM_PROFILE) += platform_profile.o obj-$(CONFIG_ACPI_NFIT) += nfit/ obj-$(CONFIG_ACPI_NUMA) += numa/ obj-$(CONFIG_ACPI) += acpi_memhotplug.o
drivers/acpi/platform_profile.c new file +181 -0
181 lines not on this page · raw message
include/linux/platform_profile.h new file +39 -0
@@ -0,0 +1,39 @@ +/* SPDX-License-Identifier: GPL-2.0-or-later */ +/* +* Platform profile sysfs interface +* +* See Documentation/ABI/testing/sysfs-platform_profile.rst for more +* information. +*/ + +#ifndef _PLATFORM_PROFILE_H_ +#define _PLATFORM_PROFILE_H_ + +#include <linux/bitops.h> + +/* +* If more options are added please update profile_names +* array in platform-profile.c and sysfs-platform-profile.rst +* documentation. +*/ + +enum platform_profile_option { +PLATFORM_PROFILE_LOW , +PLATFORM_PROFILE_COOL , +PLATFORM_PROFILE_QUIET , +PLATFORM_PROFILE_BALANCED , +PLATFORM_PROFILE_PERFORM , +PLATFORM_PROFILE_LAST ,/*must always be last */ +}; + +struct platform_profile_handler { +unsigned long choices[BITS_TO_LONGS (PLATFORM_PROFILE_LAST )]; +int (*profile_get)(enum platform_profile_option *profile); +int (*profile_set)(enum platform_profile_option profile); +}; + +int platform_profile_register (const struct platform_profile_handler *pprof); +int platform_profile_remove (void ); +void platform_profile_notify (void ); + +#endif /*_PLATFORM_PROFILE_H_*/
Signature · 1 line
2.28.0
Rafael J. Wysocki
maintainerRe: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
Quoted 11 lines · Mark Pearson
This is the initial implementation of the platform-profile feature. It provides the details discussed and outlined in the sysfs-platform_profile document.
Many modern systems have the ability to modify the operating profile to control aspects like fan speed, temperature and power levels. This module provides a common sysfs interface that platform modules can register against to control their individual profile options.
Signed-off-by Mark Pearson <[email protected]>
[cut]
Quoted 27 lines
include/linux/platform_profile.h new file +21
-0@@ -0,0 +1,39 @@ +/* SPDX-License-Identifier: GPL-2.0-or-later */ +/* +* Platform profile sysfs interface +* +* See Documentation/ABI/testing/sysfs-platform_profile.rst for more +* information. +*/ + +#ifndef _PLATFORM_PROFILE_H_ +#define _PLATFORM_PROFILE_H_ + +#include <linux/bitops.h> + +/* +* If more options are added please update profile_names +* array in platform-profile.c and sysfs-platform-profile.rst +* documentation. +*/ + +enum platform_profile_option { + PLATFORM_PROFILE_LOW,
include/linux/platform_profile.h line 31
Quoted 10 lines
include/linux/platform_profile.h new file +10
-0+PLATFORM_PROFILE_COOL , +PLATFORM_PROFILE_QUIET , +PLATFORM_PROFILE_BALANCED , +PLATFORM_PROFILE_PERFORM , + PLATFORM_PROFILE_LAST, /*must always be last */ +}; + +struct platform_profile_handler { +unsigned long choices[BITS_TO_LONGS (PLATFORM_PROFILE_LAST )]; +int (*profile_get)(enum platform_profile_option *profile);
I'm not sure why this callback is necessary and, provided that there is a good enough reason, why it cannot return an enum platform_profile_option value.
In principle, if ->profile_set() returns 0, the requested profile can be saved in a static var and then returned by subsequent "read" operations.
Quoted 9 lines
include/linux/platform_profile.h new file +8
-1+ int (*profile_set)(enum platform_profile_option profile); +}; + +int platform_profile_register (const struct platform_profile_handler *pprof); +int platform_profile_remove (void ); +void platform_profile_notify (void ); + +#endif /*_PLATFORM_PROFILE_H_*/ --
Re: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
2020. december 16., szerda 19:13 keltezéssel, Rafael J. Wysocki írta:
Quoted 30 lines · Mark Pearson
Quoted 11 lines
This is the initial implementation of the platform-profile feature. It provides the details discussed and outlined in the sysfs-platform_profile document.
Many modern systems have the ability to modify the operating profile to control aspects like fan speed, temperature and power levels. This module provides a common sysfs interface that platform modules can register against to control their individual profile options.
Signed-off-by Mark Pearson <[email protected]>[...]
include/linux/platform_profile.h line 31
Quoted 12 lines
include/linux/platform_profile.h new file +12
-0+enum platform_profile_option { +PLATFORM_PROFILE_LOW , +PLATFORM_PROFILE_COOL , +PLATFORM_PROFILE_QUIET , +PLATFORM_PROFILE_BALANCED , +PLATFORM_PROFILE_PERFORM , +PLATFORM_PROFILE_LAST ,/*must always be last */ +}; + +struct platform_profile_handler { +unsigned long choices[BITS_TO_LONGS (PLATFORM_PROFILE_LAST )]; +int (*profile_get)(enum platform_profile_option *profile);I'm not sure why this callback is necessary and, provided that there is a good enough reason, why it cannot return an enum
platform_profile_optionvalue.
Quoted 4 lines
In principle, if ->profile_set() returns 0, the requested profile can be saved in a static var and then returned by subsequent "read" operations.
It is possible that the platform profile can be changed with (e.g.) a dedicated button (commonly found on laptops), in which case there needs to be a mechanism to retrieve the new profile, which would not be possible without introducing something else in place of that getter - unless I'm missing something obvious.
Regards,
Barnabás Pőcze
Rafael J. Wysocki
maintainerRe: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
Quoted 38 lines · Barnabás Pőcze
2020. december 16., szerda 19:13 keltezéssel, Rafael J. Wysocki írta:
Quoted 30 lines · Mark Pearson
Quoted 11 lines
This is the initial implementation of the platform-profile feature. It provides the details discussed and outlined in the sysfs-platform_profile document.
Many modern systems have the ability to modify the operating profile to control aspects like fan speed, temperature and power levels. This module provides a common sysfs interface that platform modules can register against to control their individual profile options.
Signed-off-by Mark Pearson <[email protected]>[...]
include/linux/platform_profile.h line 31
Quoted 12 lines
include/linux/platform_profile.h new file +12
-0+enum platform_profile_option { +PLATFORM_PROFILE_LOW , +PLATFORM_PROFILE_COOL , +PLATFORM_PROFILE_QUIET , +PLATFORM_PROFILE_BALANCED , +PLATFORM_PROFILE_PERFORM , +PLATFORM_PROFILE_LAST ,/*must always be last */ +}; + +struct platform_profile_handler { +unsigned long choices[BITS_TO_LONGS (PLATFORM_PROFILE_LAST )]; +int (*profile_get)(enum platform_profile_option *profile);I'm not sure why this callback is necessary and, provided that there is a good enough reason, why it cannot return an enum
platform_profile_optionvalue.Quoted 4 lines
In principle, if ->profile_set() returns 0, the requested profile can be saved in a static var and then returned by subsequent "read" operations.
Quoted 4 lines
It is possible that the platform profile can be changed with (e.g.) a dedicated button (commonly found on laptops), in which case there needs to be a mechanism to retrieve the new profile, which would not be possible without introducing something else in place of that getter - unless I'm missing something obvious.
Fair enough.
The other question remains, then.
Re: [External] Re: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
Hi Rafael,
Quoted 39 lines · Rafael J. Wysocki
Quoted 38 lines · Barnabás Pőcze
2020. december 16., szerda 19:13 keltezéssel, Rafael J. Wysocki írta:
Quoted 34 lines · Mark Pearson
Quoted 11 lines
This is the initial implementation of the platform-profile feature. It provides the details discussed and outlined in the sysfs-platform_profile document.
Many modern systems have the ability to modify the operating profile to control aspects like fan speed, temperature and power levels. This module provides a common sysfs interface that platform modules can register against to control their individual profile options.
Signed-off-by Mark Pearson <[email protected]>[...]
include/linux/platform_profile.h line 31
Quoted 12 lines
include/linux/platform_profile.h new file +12
-0+enum platform_profile_option { +PLATFORM_PROFILE_LOW , +PLATFORM_PROFILE_COOL , +PLATFORM_PROFILE_QUIET , +PLATFORM_PROFILE_BALANCED , +PLATFORM_PROFILE_PERFORM , +PLATFORM_PROFILE_LAST ,/*must always be last */ +}; + +struct platform_profile_handler { +unsigned long choices[BITS_TO_LONGS (PLATFORM_PROFILE_LAST )]; +int (*profile_get)(enum platform_profile_option *profile);I'm not sure why this callback is necessary and, provided that there is a good enough reason, why it cannot return an enum
platform_profile_optionvalue.In principle, if ->profile_set() returns 0, the requested profile can be saved in a static var and then returned by subsequent "read" operations.
Quoted 9 lines
Quoted 4 lines
It is possible that the platform profile can be changed with (e.g.) a dedicated button (commonly found on laptops), in which case there needs to be a mechanism to retrieve the new profile, which would not be possible without introducing something else in place of that getter - unless I'm missing something obvious.
Fair enough.
The other question remains, then.
My thinking here that I shouldn't make assumptions for future platform implementations - there may be valid cases in the future where being able to return an error condition if there was an error would be useful.
Just trying to keep this somewhat future proof. Returning an error condition seemed a useful thing to have available.
Mark
Rafael J. Wysocki
maintainerRe: [External] Re: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
Quoted 50 lines · Mark Pearson
Hi Rafael,
Quoted 46 lines · Rafael J. Wysocki
Quoted 38 lines · Barnabás Pőcze
2020. december 16., szerda 19:13 keltezéssel, Rafael J. Wysocki írta:
Quoted 30 lines · Mark Pearson
Quoted 11 lines
This is the initial implementation of the platform-profile feature. It provides the details discussed and outlined in the sysfs-platform_profile document.
Many modern systems have the ability to modify the operating profile to control aspects like fan speed, temperature and power levels. This module provides a common sysfs interface that platform modules can register against to control their individual profile options.
Signed-off-by Mark Pearson <[email protected]>[...]
include/linux/platform_profile.h line 31
Quoted 12 lines
include/linux/platform_profile.h new file +12
-0+enum platform_profile_option { +PLATFORM_PROFILE_LOW , +PLATFORM_PROFILE_COOL , +PLATFORM_PROFILE_QUIET , +PLATFORM_PROFILE_BALANCED , +PLATFORM_PROFILE_PERFORM , +PLATFORM_PROFILE_LAST ,/*must always be last */ +}; + +struct platform_profile_handler { +unsigned long choices[BITS_TO_LONGS (PLATFORM_PROFILE_LAST )]; +int (*profile_get)(enum platform_profile_option *profile);I'm not sure why this callback is necessary and, provided that there is a good enough reason, why it cannot return an enum
platform_profile_optionvalue.Quoted 4 lines
In principle, if ->profile_set() returns 0, the requested profile can be saved in a static var and then returned by subsequent "read" operations.
Quoted 4 lines
It is possible that the platform profile can be changed with (e.g.) a dedicated button (commonly found on laptops), in which case there needs to be a mechanism to retrieve the new profile, which would not be possible without introducing something else in place of that getter - unless I'm missing something obvious.
Fair enough.
Quoted 8 lines
Quoted 2 lines
The other question remains, then.
My thinking here that I shouldn't make assumptions for future platform implementations - there may be valid cases in the future where being able to return an error condition if there was an error would be useful.
Just trying to keep this somewhat future proof. Returning an error condition seemed a useful thing to have available.
You can still return an error while returning a platform_profile_option value.
Just add a special value representing an error to that set.
Re: [External] Re: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
Quoted 57 lines · Rafael J. Wysocki
Quoted 56 lines · Mark Pearson
Hi Rafael,
Quoted 39 lines · Rafael J. Wysocki
Quoted 38 lines · Barnabás Pőcze
2020. december 16., szerda 19:13 keltezéssel, Rafael J. Wysocki írta:
Quoted 34 lines · Mark Pearson
Quoted 11 lines
This is the initial implementation of the platform-profile feature. It provides the details discussed and outlined in the sysfs-platform_profile document.
Many modern systems have the ability to modify the operating profile to control aspects like fan speed, temperature and power levels. This module provides a common sysfs interface that platform modules can register against to control their individual profile options.
Signed-off-by Mark Pearson <[email protected]>[...]
include/linux/platform_profile.h line 31
Quoted 12 lines
include/linux/platform_profile.h new file +12
-0+enum platform_profile_option { +PLATFORM_PROFILE_LOW , +PLATFORM_PROFILE_COOL , +PLATFORM_PROFILE_QUIET , +PLATFORM_PROFILE_BALANCED , +PLATFORM_PROFILE_PERFORM , +PLATFORM_PROFILE_LAST ,/*must always be last */ +}; + +struct platform_profile_handler { +unsigned long choices[BITS_TO_LONGS (PLATFORM_PROFILE_LAST )]; +int (*profile_get)(enum platform_profile_option *profile);I'm not sure why this callback is necessary and, provided that there is a good enough reason, why it cannot return an enum
platform_profile_optionvalue.In principle, if ->profile_set() returns 0, the requested profile can be saved in a static var and then returned by subsequent "read" operations.
Quoted 9 lines
Quoted 4 lines
It is possible that the platform profile can be changed with (e.g.) a dedicated button (commonly found on laptops), in which case there needs to be a mechanism to retrieve the new profile, which would not be possible without introducing something else in place of that getter - unless I'm missing something obvious.
Fair enough.
The other question remains, then.
My thinking here that I shouldn't make assumptions for future platform implementations - there may be valid cases in the future where being able to return an error condition if there was an error would be useful.
Quoted 7 lines
Quoted 2 lines
Just trying to keep this somewhat future proof. Returning an error condition seemed a useful thing to have available.
You can still return an error while returning a
platform_profile_optionvalue.Just add a special value representing an error to that set.
I'd like to understand what is better about that approach than having an error and a returnable parameter?
I'm probably missing something obvious but if I add an extra platform_profile option (e.g PLATFORM_PROFILE_ERROR) to be used in an error case (and return just an enum platform_profile_option) it seems I lose the granularity of being able to return a specific error condition. It doesn't feel like an improvement.
Let me know what I'm missing.
Thanks
Mark
Rafael J. Wysocki
maintainerRe: [External] Re: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
Quoted 67 lines · Mark Pearson
Quoted 57 lines · Rafael J. Wysocki
Quoted 56 lines · Mark Pearson
Hi Rafael,
Quoted 39 lines · Rafael J. Wysocki
Quoted 38 lines · Barnabás Pőcze
2020. december 16., szerda 19:13 keltezéssel, Rafael J. Wysocki írta:
Quoted 34 lines · Mark Pearson
Quoted 11 lines
This is the initial implementation of the platform-profile feature. It provides the details discussed and outlined in the sysfs-platform_profile document.
Many modern systems have the ability to modify the operating profile to control aspects like fan speed, temperature and power levels. This module provides a common sysfs interface that platform modules can register against to control their individual profile options.
Signed-off-by Mark Pearson <[email protected]>[...]
Review
Quoted 12 lines
(quoted diff) +12
-0+enum platform_profile_option { + PLATFORM_PROFILE_LOW, + PLATFORM_PROFILE_COOL, + PLATFORM_PROFILE_QUIET, + PLATFORM_PROFILE_BALANCED, + PLATFORM_PROFILE_PERFORM, + PLATFORM_PROFILE_LAST, /*must always be last */ +}; + +struct platform_profile_handler { + unsigned long choices[BITS_TO_LONGS(PLATFORM_PROFILE_LAST)]; + int (*profile_get)(enum platform_profile_option *profile);I'm not sure why this callback is necessary and, provided that there is a good enough reason, why it cannot return an enum
platform_profile_optionvalue.In principle, if ->profile_set() returns 0, the requested profile can be saved in a static var and then returned by subsequent "read" operations.
Quoted 9 lines
Quoted 4 lines
It is possible that the platform profile can be changed with (e.g.) a dedicated button (commonly found on laptops), in which case there needs to be a mechanism to retrieve the new profile, which would not be possible without introducing something else in place of that getter - unless I'm missing something obvious.
Fair enough.
The other question remains, then.
My thinking here that I shouldn't make assumptions for future platform implementations - there may be valid cases in the future where being able to return an error condition if there was an error would be useful.
Quoted 7 lines
Quoted 2 lines
Just trying to keep this somewhat future proof. Returning an error condition seemed a useful thing to have available.
You can still return an error while returning a
platform_profile_optionvalue.Just add a special value representing an error to that set.
Quoted 8 lines
I'd like to understand what is better about that approach than having an error and a returnable parameter?
I'm probably missing something obvious but if I add an extra
platform_profileoption (e.gPLATFORM_PROFILE_ERROR) to be used in an error case (and return just an enumplatform_profile_option) it seems I lose the granularity of being able to return a specific error condition. It doesn't feel like an improvement.
And what's the user expected to do about the different error codes that can be returned?
Re: [External] Re: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
Quoted 71 lines · Rafael J. Wysocki
Quoted 70 lines · Mark Pearson
Quoted 57 lines · Rafael J. Wysocki
Quoted 56 lines · Mark Pearson
Hi Rafael,
Quoted 39 lines · Rafael J. Wysocki
Quoted 38 lines · Barnabás Pőcze
2020. december 16., szerda 19:13 keltezéssel, Rafael J. Wysocki írta:
Quoted 34 lines · Mark Pearson
Quoted 11 lines
This is the initial implementation of the platform-profile feature. It provides the details discussed and outlined in the sysfs-platform_profile document.
Many modern systems have the ability to modify the operating profile to control aspects like fan speed, temperature and power levels. This module provides a common sysfs interface that platform modules can register against to control their individual profile options.
Signed-off-by Mark Pearson <[email protected]>[...]
Review
Quoted 12 lines
(quoted diff) +12
-0+enum platform_profile_option { + PLATFORM_PROFILE_LOW, + PLATFORM_PROFILE_COOL, + PLATFORM_PROFILE_QUIET, + PLATFORM_PROFILE_BALANCED, + PLATFORM_PROFILE_PERFORM, + PLATFORM_PROFILE_LAST, /*must always be last */ +}; + +struct platform_profile_handler { + unsigned long choices[BITS_TO_LONGS(PLATFORM_PROFILE_LAST)]; + int (*profile_get)(enum platform_profile_option *profile);I'm not sure why this callback is necessary and, provided that there is a good enough reason, why it cannot return an enum
platform_profile_optionvalue.In principle, if ->profile_set() returns 0, the requested profile can be saved in a static var and then returned by subsequent "read" operations.
Quoted 9 lines
Quoted 4 lines
It is possible that the platform profile can be changed with (e.g.) a dedicated button (commonly found on laptops), in which case there needs to be a mechanism to retrieve the new profile, which would not be possible without introducing something else in place of that getter - unless I'm missing something obvious.
Fair enough.
The other question remains, then.
My thinking here that I shouldn't make assumptions for future platform implementations - there may be valid cases in the future where being able to return an error condition if there was an error would be useful.
Quoted 7 lines
Quoted 2 lines
Just trying to keep this somewhat future proof. Returning an error condition seemed a useful thing to have available.
You can still return an error while returning a
platform_profile_optionvalue.Just add a special value representing an error to that set.
I'd like to understand what is better about that approach than having an error and a returnable parameter?
Quoted 9 lines
Quoted 5 lines
I'm probably missing something obvious but if I add an extra
platform_profileoption (e.gPLATFORM_PROFILE_ERROR) to be used in an error case (and return just an enumplatform_profile_option) it seems I lose the granularity of being able to return a specific error condition. It doesn't feel like an improvement.And what's the user expected to do about the different error codes that can be returned?
From my experiences when something fails I would rather have more information than less. I'm probably over thinking it though.
Looking at it again, from my Lenovo platform profile implementation perspective I have no objections. It's hard to argue a point without having a hard requirement or example :) I'll go ahead with your suggestion of just returning the profile.
Thank you for the review
Mark
Re: [External] Re: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
In reply to Rafael J. Wysocki2020. december 17., csütörtök 14:36 keltezéssel, Rafael J. Wysocki <[email protected]> írta:
Quoted 15 lines
[...]
Quoted 14 lines
Quoted 11 lines
Quoted 6 lines
My thinking here that I shouldn't make assumptions for future platform implementations - there may be valid cases in the future where being able to return an error condition if there was an error would be useful.
Just trying to keep this somewhat future proof. Returning an error condition seemed a useful thing to have available.
You can still return an error while returning a
platform_profile_optionvalue.Just add a special value representing an error to that set.
I'd like to understand what is better about that approach than having an error and a returnable parameter?
Quoted 8 lines
Quoted 5 lines
I'm probably missing something obvious but if I add an extra
platform_profileoption (e.gPLATFORM_PROFILE_ERROR) to be used in an error case (and return just an enumplatform_profile_option) it seems I lose the granularity of being able to return a specific error condition. It doesn't feel like an improvement.And what's the user expected to do about the different error codes that can be returned?
Even assuming the users of the API cannot or will not handle different errors differently, who would benefit from getting rid of this information which may be an aid in debugging for those who know what they're looking at?
And if a new enum value is introduced to signal an error condition, how is that going to be communicated to the users? A magic string like "error" or "-1"? Or under a single errno like -EIO? Personally, I believe neither of these two solutions are better than returning the actual errno which is deemed most appropriate by the platform profile handler. Or am I missing a third way?
Regards,
Barnabás Pőcze
Rafael J. Wysocki
maintainerRe: [External] Re: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
Quoted 27 lines · Barnabás Pőcze
2020. december 17., csütörtök 14:36 keltezéssel, Rafael J. Wysocki <[email protected]> írta:
Quoted 15 lines
[...]
Quoted 14 lines
Quoted 11 lines
Quoted 6 lines
My thinking here that I shouldn't make assumptions for future platform implementations - there may be valid cases in the future where being able to return an error condition if there was an error would be useful.
Just trying to keep this somewhat future proof. Returning an error condition seemed a useful thing to have available.
You can still return an error while returning a
platform_profile_optionvalue.Just add a special value representing an error to that set.
I'd like to understand what is better about that approach than having an error and a returnable parameter?
Quoted 8 lines
Quoted 5 lines
I'm probably missing something obvious but if I add an extra
platform_profileoption (e.gPLATFORM_PROFILE_ERROR) to be used in an error case (and return just an enumplatform_profile_option) it seems I lose the granularity of being able to return a specific error condition. It doesn't feel like an improvement.And what's the user expected to do about the different error codes that can be returned?
Quoted 7 lines
Even assuming the users of the API cannot or will not handle different errors differently, who would benefit from getting rid of this information which may be an aid in debugging for those who know what they're looking at?
And if a new enum value is introduced to signal an error condition, how is that going to be communicated to the users? A magic string like "error" or "-1"? Or under a single errno like
-EIO?
Yes.
Quoted 3 lines
Personally, I believe neither of these two
solutions are better than returning the actual errno which is deemed most appropriate by the platform profile handler. Or am I missing a third way?
Can we please defer this until we actually have a driver needing to return different error values from ->get_profile() (and I find it hard to believe that there will be any drivers like that)?
Let's do the simpler thing until we have a real need to do the more complicated one.
Otherwise we're preparing for things that may never happen.
Re: [External] Re: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
Quoted 38 lines · Rafael J. Wysocki
Quoted 27 lines · Barnabás Pőcze
2020. december 17., csütörtök 14:36 keltezéssel, Rafael J. Wysocki <[email protected]> írta:
Quoted 15 lines
[...]
Quoted 14 lines
Quoted 11 lines
Quoted 6 lines
My thinking here that I shouldn't make assumptions for future platform implementations - there may be valid cases in the future where being able to return an error condition if there was an error would be useful.
Just trying to keep this somewhat future proof. Returning an error condition seemed a useful thing to have available.
You can still return an error while returning a
platform_profile_optionvalue.Just add a special value representing an error to that set.
I'd like to understand what is better about that approach than having an error and a returnable parameter?
Quoted 8 lines
Quoted 5 lines
I'm probably missing something obvious but if I add an extra
platform_profileoption (e.gPLATFORM_PROFILE_ERROR) to be used in an error case (and return just an enumplatform_profile_option) it seems I lose the granularity of being able to return a specific error condition. It doesn't feel like an improvement.And what's the user expected to do about the different error codes that can be returned?
Quoted 7 lines
Even assuming the users of the API cannot or will not handle different errors differently, who would benefit from getting rid of this information which may be an aid in debugging for those who know what they're looking at?
And if a new enum value is introduced to signal an error condition, how is that going to be communicated to the users? A magic string like "error" or "-1"? Or under a single errno like
-EIO?Yes.
Quoted 7 lines
Quoted 3 lines
Personally, I believe neither of these two
solutions are better than returning the actual errno which is deemed most appropriate by the platform profile handler. Or am I missing a third way?Can we please defer this until we actually have a driver needing to return different error values from ->get_profile() (and I find it hard to believe that there will be any drivers like that)?
I can maybe give an example. On Microsoft Surface devices, the performance mode / platform profile is set via a request to the embedded controller and can be queried the same way. This request can fail (most notably with ETIMEDOUT and EREMOTEIO). I think at least being able to show users an error in this case would be helpful.
A driver for that is currently at [1], but I haven't adapted that yet to the platform profile patchset.
On the other hand, I can also query and store the profile when loading the driver and then update it when it's changed. That'd require that no one else changes the profile, but I think we can safely assume that.
Regards,
Max
Quoted 6 lines
Let's do the simpler thing until we have a real need to do the more complicated one.
Otherwise we're preparing for things that may never happen.
Rafael J. Wysocki
maintainerRe: [External] Re: [PATCH v6 2/3] ACPI: platform-profile: Add platform profile support
Quoted 50 lines · Maximilian Luz
Quoted 38 lines · Rafael J. Wysocki
Quoted 27 lines · Barnabás Pőcze
2020. december 17., csütörtök 14:36 keltezéssel, Rafael J. Wysocki <[email protected]> írta:
Quoted 15 lines
[...]
Quoted 14 lines
Quoted 11 lines
Quoted 6 lines
My thinking here that I shouldn't make assumptions for future platform implementations - there may be valid cases in the future where being able to return an error condition if there was an error would be useful.
Just trying to keep this somewhat future proof. Returning an error condition seemed a useful thing to have available.
You can still return an error while returning a
platform_profile_optionvalue.Just add a special value representing an error to that set.
I'd like to understand what is better about that approach than having an error and a returnable parameter?
Quoted 8 lines
Quoted 5 lines
I'm probably missing something obvious but if I add an extra
platform_profileoption (e.gPLATFORM_PROFILE_ERROR) to be used in an error case (and return just an enumplatform_profile_option) it seems I lose the granularity of being able to return a specific error condition. It doesn't feel like an improvement.And what's the user expected to do about the different error codes that can be returned?
Quoted 7 lines
Even assuming the users of the API cannot or will not handle different errors differently, who would benefit from getting rid of this information which may be an aid in debugging for those who know what they're looking at?
And if a new enum value is introduced to signal an error condition, how is that going to be communicated to the users? A magic string like "error" or "-1"? Or under a single errno like
-EIO?Yes.
Quoted 7 lines
Quoted 3 lines
Personally, I believe neither of these two
solutions are better than returning the actual errno which is deemed most appropriate by the platform profile handler. Or am I missing a third way?Can we please defer this until we actually have a driver needing to return different error values from ->get_profile() (and I find it hard to believe that there will be any drivers like that)?
Quoted 5 lines
I can maybe give an example. On Microsoft Surface devices, the performance mode / platform profile is set via a request to the embedded controller and can be queried the same way. This request can fail (most notably with ETIMEDOUT and EREMOTEIO). I think at least being able to show users an error in this case would be helpful.
OK, fair enough, let's keep it the way it is.
PATCH v6 3/3 platform/x86: thinkpad_acpi: Add platform profile support
In reply to Mark PearsonAdd support to thinkpad_acpi for Lenovo platforms that have DYTC version 5 support or newer to use the platform profile feature.
This will allow users to determine and control the platform modes between low-power, balanced operation and performance modes.
---
Changes in v2:
Address (hopefully) all recommendations from review including:
- use IS_ENABLED instead of IS_DEFINED
- update driver to work with all the fixes in platform_profile update
- improve error handling for invalid inputs
- move tracking of current profile mode into this driver
Changes in v3:
- version update for patch series
Changes in v4:
- Rebase on top of palm sensor patch which led to a little bit of file restructuring/clean up
- Use BIT macro where applicable
- Formatting fixes
- Check sysfs node created on exit function
- implement and use DYTC_SET_COMMAND macro
- in case of failure setting performance mode make sure CQL mode is enabled again before returning.
- Clean up initialisation and error handling code
Changes in v5:
- Use atomic_int with ignoring events
- Add mutex when accessing ACPI information
- Clean up registration code
- Use cached value in profile_get function
- Add dytc_cql_command function to clean up and provide common handler
- Update to work with changes in platform_profile implementation
Changes in v6:
- Update file to build against update in v6 platform_profile
drivers/platform/x86/thinkpad_acpi.c | 292 ++++++++++++++++++++++++++- 1 file changed, 286 insertions(+), 6 deletions(-)
drivers/platform/x86/thinkpad_acpi.c +286 -6
@@ -66,6 +66,7 @@#include <linux/acpi.h> #include <linux/pci.h> #include <linux/power_supply.h> +#include <linux/platform_profile.h> #include <sound/core.h> #include <sound/control.h> #include <sound/initval.h>
@@ -9843,16 +9844,27 @@ static bool has_lapsensor;static bool palm_state;static bool lap_state; -static int lapsensor_get (bool *present,bool *state) +static int dytc_command (int command,int *output) {acpi_handle dytc_handle; -int output; - *present = false; -if (ACPI_FAILURE (acpi_get_handle (hkey_handle,"DYTC" , &dytc_handle))) +if (ACPI_FAILURE (acpi_get_handle (hkey_handle,"DYTC" , &dytc_handle))) { +/* Platform doesn't support DYTC */ return -ENODEV ; -if (!acpi_evalf (dytc_handle, &output,NULL ,"dd" ,DYTC_CMD_GET )) + } +if (!acpi_evalf (dytc_handle, output,NULL ,"dd" , command))return -EIO ; +return 0 ; +} + +static int lapsensor_get (bool *present,bool *state) +{ +int output, err; + + *present = false; + err =dytc_command (DYTC_CMD_GET , &output); +if (err) +return err; *present = true;/*If we get his far, we have lapmode support*/ *state = output &BIT (DYTC_GET_LAPMODE_BIT ) ? true : false;
@@ -9971,6 +9983,262 @@ static struct ibm_struct proxsensor_driver_data = { .exit = proxsensor_exit, }; +#if IS_ENABLED (CONFIG_ACPI_PLATFORM_PROFILE ) + +/************************************************************************* +* DYTC Platform Profile interface +*/ + +#define DYTC_CMD_QUERY 0/* To get DYTC status - enable/revision */ +#define DYTC_CMD_SET 1/* To enable/disable IC function mode */ +#define DYTC_CMD_RESET 0x1ff/* To reset back to default */ + +#define DYTC_QUERY_ENABLE_BIT 8/* Bit 8 - 0 = disabled, 1 = enabled */ +#define DYTC_QUERY_SUBREV_BIT 16/* Bits 16 - 27 - sub revision */ +#define DYTC_QUERY_REV_BIT 28/* Bits 28 - 31 - revision */ + +#define DYTC_GET_FUNCTION_BIT 8/* Bits 8-11 - function setting */ +#define DYTC_GET_MODE_BIT 12/* Bits 12-15 - mode setting */ + +#define DYTC_SET_FUNCTION_BIT 12/* Bits 12-15 - function setting */ +#define DYTC_SET_MODE_BIT 16/* Bits 16-19 - mode setting */ +#define DYTC_SET_VALID_BIT 20/* Bit 20 - 1 = on, 0 = off */ + +#define DYTC_FUNCTION_STD 0/* Function = 0, standard mode */ +#define DYTC_FUNCTION_CQL 1/* Function = 1, lap mode */ +#define DYTC_FUNCTION_MMC 11/* Function = 11, desk mode */ + +#define DYTC_MODE_PERFORM 2/* High power mode aka performance */ +#define DYTC_MODE_QUIET 3/* Low power mode aka quiet */ +#define DYTC_MODE_BALANCE 0xF/* Default mode aka balanced */ + +#define DYTC_SET_COMMAND (function, mode, on) \ + (DYTC_CMD_SET | (function) << DYTC_SET_FUNCTION_BIT | \ + (mode) << DYTC_SET_MODE_BIT | \ + (on) << DYTC_SET_VALID_BIT) + +#define DYTC_DISABLE_CQL DYTC_SET_COMMAND(DYTC_FUNCTION_CQL, DYTC_MODE_BALANCE, 0) + +#define DYTC_ENABLE_CQL DYTC_SET_COMMAND(DYTC_FUNCTION_CQL, DYTC_MODE_BALANCE, 1) + +static bool dytc_profile_available; +static enum platform_profile_option dytc_current_profile; +static atomic_t dytc_ignore_event =ATOMIC_INIT (0 ); +static DEFINE_MUTEX (dytc_mutex); + +static int convert_dytc_to_profile (int dytcmode,enum platform_profile_option *profile) +{ +switch (dytcmode) { +case DYTC_MODE_QUIET : + *profile =PLATFORM_PROFILE_LOW ; +break ; +case DYTC_MODE_BALANCE : + *profile =PLATFORM_PROFILE_BALANCED ; +break ; +case DYTC_MODE_PERFORM : + *profile =PLATFORM_PROFILE_PERFORM ; +break ; +default :/* Unknown mode */ +return -EINVAL ; + } +return 0 ; +} + +static int convert_profile_to_dytc (enum platform_profile_option profile,int *perfmode) +{ +switch (profile) { +case PLATFORM_PROFILE_QUIET : + *perfmode =DYTC_MODE_QUIET ; +break ; +case PLATFORM_PROFILE_BALANCED : + *perfmode =DYTC_MODE_BALANCE ; +break ; +case PLATFORM_PROFILE_PERFORM : + *perfmode =DYTC_MODE_PERFORM ; +break ; +default :/* Unknown profile */ +return -EOPNOTSUPP ; + } +return 0 ; +} + +/* +* dytc_profile_get: Function to register with platform_profile +* handler. Returns current platform profile. +*/ +int dytc_profile_get (enum platform_profile_option *profile) +{ + *profile = dytc_current_profile; +return 0 ; +} + +/* +* Helper function - check if we are in CQL mode and if we are +* - disable CQL, +* - run the command +* - enable CQL +* If not in CQL mode, just run the command +*/ +int dytc_cql_command (int command,int *output) +{ +int err, cmd_err, dummy; +int cur_funcmode; + +/* Determine if we are in CQL mode. This alters the commands we do */ + err =dytc_command (DYTC_CMD_GET , output); +if (err) +return err; + + cur_funcmode = (*output >>DYTC_GET_FUNCTION_BIT ) &0xF ; +/* Check if we're OK to return immediately */ +if ((command ==DYTC_CMD_GET ) && (cur_funcmode !=DYTC_FUNCTION_CQL )) +return 0 ; + +if (cur_funcmode ==DYTC_FUNCTION_CQL ) { +atomic_inc (&dytc_ignore_event); + err =dytc_command (DYTC_DISABLE_CQL , &dummy); +if (err) +return err; + } + + cmd_err =dytc_command (command, output); +/* Check return condition after we've restored CQL state */ + +if (cur_funcmode ==DYTC_FUNCTION_CQL ) { + err =dytc_command (DYTC_ENABLE_CQL , &dummy); +if (err) +return err; + } + +return cmd_err; +} + +/* +* dytc_profile_set: Function to register with platform_profile +* handler. Sets current platform profile. +*/ +int dytc_profile_set (enum platform_profile_option profile) +{ +int output; +int err; + +if (!dytc_profile_available) +return -ENODEV ; + + err =mutex_lock_interruptible (&dytc_mutex); +if (err) +return err; + +if (profile ==PLATFORM_PROFILE_BALANCED ) { +/* To get back to balanced mode we just issue a reset command */ + err =dytc_command (DYTC_CMD_RESET , &output); +if (err) + goto unlock; + }else { +int perfmode; + + err =convert_profile_to_dytc (profile, &perfmode); +if (err) + goto unlock; + +/* Determine if we are in CQL mode. This alters the commands we do */ + err =dytc_cql_command (DYTC_SET_COMMAND (DYTC_FUNCTION_MMC , perfmode,1 ), &output); +if (err) + goto unlock; + } +/* Success - update current profile */ + dytc_current_profile = profile; +unlock: +mutex_unlock (&dytc_mutex); +return err; +} + +static void dytc_profile_refresh (void ) +{ +enum platform_profile_option profile; +int output, err; +int perfmode; + +mutex_lock (&dytc_mutex); + err =dytc_cql_command (DYTC_CMD_GET , &output); +mutex_unlock (&dytc_mutex); +if (err) +return ; + + perfmode = (output >>DYTC_GET_MODE_BIT ) &0xF ; +convert_dytc_to_profile (perfmode, &profile); +if (profile != dytc_current_profile) { + dytc_current_profile = profile; +platform_profile_notify (); + } +} + +static struct platform_profile_handler dytc_profile = { + .profile_get = dytc_profile_get, + .profile_set = dytc_profile_set, +}; + +static int tpacpi_dytc_profile_init (struct ibm_init_struct *iibm) +{ +int err, output; + +/* Setup supported modes */ +set_bit (PLATFORM_PROFILE_LOW , dytc_profile.choices); +set_bit (PLATFORM_PROFILE_BALANCED , dytc_profile.choices); +set_bit (PLATFORM_PROFILE_PERFORM , dytc_profile.choices); + + dytc_profile_available = false; + err =dytc_command (DYTC_CMD_QUERY , &output); +/* +* If support isn't available (ENODEV) then don't return an error +* and don't create the sysfs group +*/ +if (err == -ENODEV ) +return 0 ; +/* For all other errors we can flag the failure */ +if (err) +return err; + +/* Check DYTC is enabled and supports mode setting */ +if (output &BIT (DYTC_QUERY_ENABLE_BIT )) { +/* Only DYTC v5.0 and later has this feature. */ +int dytc_version; + + dytc_version = (output >>DYTC_QUERY_REV_BIT ) &0xF ; +if (dytc_version >=5 ) { +dbg_printk (TPACPI_DBG_INIT , +"DYTC version %d: thermal mode available\n" , dytc_version); +/* Create platform_profile structure and register */ + err =platform_profile_register (&dytc_profile); +/* +* If for some reason platform_profiles aren't enabled +* don't quit terminally. +*/ +if (err) +return 0 ; + + dytc_profile_available = true; +/* Ensure initial values are correct */ +dytc_profile_refresh (); + } + } +return 0 ; +} + +static void dytc_profile_exit (void ) +{ +if (dytc_profile_available) { + dytc_profile_available = false; +platform_profile_remove (); + } +} + +static struct ibm_struct dytc_profile_driver_data = { + .name ="dytc-profile" , + .exit = dytc_profile_exit, +}; +#endif /* CONFIG_ACPI_PLATFORM_PROFILE */ +/**************************************************************************** **************************************************************************** *
@@ -10019,8 +10287,14 @@ static void tpacpi_driver_event(const unsigned int hkey_event)mutex_unlock (&kbdlight_mutex); } -if (hkey_event ==TP_HKEY_EV_THM_CSM_COMPLETED ) +if (hkey_event ==TP_HKEY_EV_THM_CSM_COMPLETED ) {lapsensor_refresh (); +#if IS_ENABLED (CONFIG_ACPI_PLATFORM_PROFILE ) +/* If we are already accessing DYTC then skip dytc update */ +if (!atomic_add_unless (&dytc_ignore_event,-1 ,0 )) +dytc_profile_refresh (); +#endif + } }static void hotkey_driver_event (const unsigned int scancode)
@@ -10463,6 +10737,12 @@ static struct ibm_init_struct ibms_init[] __initdata = { .init = tpacpi_proxsensor_init, .data = &proxsensor_driver_data, }, +#if IS_ENABLED (CONFIG_ACPI_PLATFORM_PROFILE ) + { + .init = tpacpi_dytc_profile_init, + .data = &dytc_profile_driver_data, + }, +#endif };static int __init set_ibm_param (const char *val,const struct kernel_param *kp)
Signature · 1 line
2.28.0
Rafael J. Wysocki
maintainerQuoted 53 lines · Mark Pearson
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_profilesysfs API which offers a generic API for selecting the performance-profile of these automatic-mechanisms.Co-developed-by Mark Pearson <[email protected]>Signed-off-by Mark Pearson <[email protected]>Signed-off-by Hans de Goede <[email protected]>---
Changes in v2:
- updated to rst format
Changes in v3, v4, v5
- version bump along with rest of patch series
Changes in v6:
- Splitsysfs-platform_profile.rsinto ABI text and then admin guide in userspace-api section. Hope this is correct - I'm guessing a bit..../ABI/testing/sysfs-platform_profile | 24 +++++++++++ Documentation/userspace-api/index.rst | 1 + .../userspace-api/sysfs-platform_profile.rst | 43 +++++++++++++++++++ 3 files changed, 68 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-platform_profile create mode 100644 Documentation/userspace-api/sysfs-platform_profile.rstDocumentation/ABI/testing/sysfs-platform_profile new file +14
-0@@ -0,0 +1,24 @@ +What: /sys/firmware/acpi/platform_profile_choices +Date: October 2020 +Contact: Hans de Goede <[email protected]> +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 + ============ ============================================
Documentation/ABI/testing/sysfs-platform_profile line 24
Quoted 10 lines
Documentation/ABI/testing/sysfs-platform_profile new file +10
-0+ + 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 <[email protected]> +Description: Reading this file gives the current selected profile for this + device. Writing this file with one of the strings from + available_profiles changes the profile to the new value.
IIUC s/available_profiles/platform_profile_choices/
Quoted 18 lines
Documentation/userspace-api/index.rst +1
-0@@ -24,6 +24,7 @@ place where this information is gathered. ioctl/index iommu media/index + sysfs-platform_profile .. only:: subproject and htmlDocumentation/userspace-api/sysfs-platform_profile.rst new file +0
-0
Documentation/userspace-api/sysfs-platform_profile.rst line 7
Quoted 7 lines
Documentation/userspace-api/sysfs-platform_profile.rst new file +7
-0@@ -0,0 +1,43 @@ +===================================================================== +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 +profile is often automatically adjusted to the load by some
After reading this one more time it looks to me like referring to the profile here is premature, it needs to be defined first.
Maybe say "The platform configuration is often ..."
Iit is also unclear what "the load" means here, so I would say something like "adjusted to the current conditions" to avoid using that term.
Quoted 37 lines
Documentation/userspace-api/sysfs-platform_profile.rst new file +36
-1+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. + + --
Hi Rafael,
Quoted 2 lines · Rafael J. Wysocki
Quoted 1 line · Mark Pearson
<snip>
Quoted 25 lines
Quoted 25 lines
Documentation/ABI/testing/sysfs-platform_profile new file +18
-0@@ -0,0 +1,24 @@ +What: /sys/firmware/acpi/platform_profile_choices +Date: October 2020 +Contact: Hans de Goede <[email protected]> +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. +
Quoted 8 lines
Documentation/ABI/testing/sysfs-platform_profile line 24
Quoted 6 lines
Documentation/ABI/testing/sysfs-platform_profile new file +6
-0+What: /sys/firmware/acpi/platform_profile +Date: October 2020 +Contact: Hans de Goede <[email protected]> +Description: Reading this file gives the current selected profile for this + device. Writing this file with one of the strings from + available_profiles changes the profile to the new value.IIUC s/available_profiles/platform_profile_choices/
Yep - I missed this one. Thank you, I'll update
Quoted 30 lines
Quoted 19 lines
Documentation/userspace-api/index.rst +1
-0@@ -24,6 +24,7 @@ place where this information is gathered. ioctl/index iommu media/index + sysfs-platform_profile .. only:: subproject and htmlDocumentation/userspace-api/sysfs-platform_profile.rst new file +0
-0Documentation/userspace-api/sysfs-platform_profile.rst line 7
Quoted 7 lines
Documentation/userspace-api/sysfs-platform_profile.rst new file +7
-0@@ -0,0 +1,43 @@ +===================================================================== +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 +profile is often automatically adjusted to the load by someAfter reading this one more time it looks to me like referring to the profile here is premature, it needs to be defined first.
Quoted 5 lines
Maybe say "The platform configuration is often ..."
Iit is also unclear what "the load" means here, so I would say something like "adjusted to the current conditions" to avoid using that term.
I'm good with both those suggestions. Thank you. I'll update
Mark