| 1 | =====================================================================
|
| 2 | Platform Profile Selection (e.g. /sys/firmware/acpi/platform_profile)
|
| 3 | =====================================================================
|
| 4 |
|
| 5 | On modern systems the platform performance, temperature, fan and other
|
| 6 | hardware related characteristics are often dynamically configurable. The
|
| 7 | platform configuration is often automatically adjusted to the current
|
| 8 | conditions by some automatic mechanism (which may very well live outside
|
| 9 | the kernel).
|
| 10 |
|
| 11 | These auto platform adjustment mechanisms often can be configured with
|
| 12 | one of several platform profiles, with either a bias towards low power
|
| 13 | operation or towards performance.
|
| 14 |
|
| 15 | The purpose of the platform_profile attribute is to offer a generic sysfs
|
| 16 | API for selecting the platform profile of these automatic mechanisms.
|
| 17 |
|
| 18 | Note that this API is only for selecting the platform profile, it is
|
| 19 | NOT a goal of this API to allow monitoring the resulting performance
|
| 20 | characteristics. Monitoring performance is best done with device/vendor
|
| 21 | specific tools, e.g. turbostat.
|
| 22 |
|
| 23 | Specifically, when selecting a high performance profile the actual achieved
|
| 24 | performance may be limited by various factors such as: the heat generated
|
| 25 | by other components, room temperature, free air flow at the bottom of a
|
| 26 | laptop, etc. It is explicitly NOT a goal of this API to let userspace know
|
| 27 | about any sub-optimal conditions which are impeding reaching the requested
|
| 28 | performance level.
|
| 29 |
|
| 30 | Since numbers on their own cannot represent the multiple variables that a
|
| 31 | profile will adjust (power consumption, heat generation, etc) this API
|
| 32 | uses strings to describe the various profiles. To make sure that userspace
|
| 33 | gets a consistent experience the sysfs-platform_profile ABI document defines
|
| 34 | a fixed set of profile names. Drivers *must* map their internal profile
|
| 35 | representation onto this fixed set.
|
| 36 |
|
| 37 | If there is no good match when mapping then a new profile name may be
|
| 38 | added. Drivers which wish to introduce new profile names must:
|
| 39 |
|
| 40 | 1. Explain why the existing profile names cannot be used.
|
| 41 | 2. Add the new profile name, along with a clear description of the
|
| 42 | expected behaviour, to the sysfs-platform_profile ABI documentation.
|
| 43 |
|
| 44 | "Custom" profile support
|
| 45 | ========================
|
| 46 | The platform_profile class also supports profiles advertising a "custom"
|
| 47 | profile. This is intended to be set by drivers when the settings in the
|
| 48 | driver have been modified in a way that a standard profile doesn't represent
|
| 49 | the current state.
|
| 50 |
|
| 51 | Multiple driver support
|
| 52 | =======================
|
| 53 | When multiple drivers on a system advertise a platform profile handler, the
|
| 54 | platform profile handler core will only advertise the profiles that are
|
| 55 | common between all drivers to the ``/sys/firmware/acpi`` interfaces.
|
| 56 |
|
| 57 | This is to ensure there is no ambiguity on what the profile names mean when
|
| 58 | all handlers don't support a profile.
|
| 59 |
|
| 60 | Individual drivers will register a 'platform_profile' class device that has
|
| 61 | similar semantics as the ``/sys/firmware/acpi/platform_profile`` interface.
|
| 62 |
|
| 63 | To discover which driver is associated with a platform profile handler the
|
| 64 | user can read the ``name`` attribute of the class device.
|
| 65 |
|
| 66 | To discover available profiles from the class interface the user can read the
|
| 67 | ``choices`` attribute.
|
| 68 |
|
| 69 | If a user wants to select a profile for a specific driver, they can do so
|
| 70 | by writing to the ``profile`` attribute of the driver's class device.
|
| 71 |
|
| 72 | This will allow users to set different profiles for different drivers on the
|
| 73 | same system. If the selected profile by individual drivers differs the
|
| 74 | platform profile handler core will display the profile 'custom' to indicate
|
| 75 | that the profiles are not the same.
|
| 76 |
|
| 77 | While the ``platform_profile`` attribute has the value ``custom``, writing a
|
| 78 | common profile from ``platform_profile_choices`` to the platform_profile
|
| 79 | attribute of the platform profile handler core will set the profile for all
|
| 80 | drivers.
|