Documentation/userspace-api/sysfs-platform_profile.rst

   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 such as 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.