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