Documentation/trace/events-power.rst

   1 =============================
   2 Subsystem Trace Points: power
   3 =============================
   4
   5 The power tracing system captures events related to power transitions
   6 within the kernel. Broadly speaking there are three major subheadings:
   7
   8   - Power state switch which reports events related to suspend (S-states),
   9     cpuidle (C-states) and cpufreq (P-states)
  10   - System clock related changes
  11   - Power domains related changes and transitions
  12
  13 This document describes what each of the tracepoints is and why they
  14 might be useful.
  15
  16 Cf. include/trace/events/power.h for the events definitions.
  17
  18 1. Power state switch events
  19 ============================
  20
  21 1.1 Trace API
  22 -----------------
  23
  24 A 'cpu' event class gathers the CPU-related events: cpuidle and
  25 cpufreq.
  26 ::
  27
  28   cpu_idle              "state=%lu cpu_id=%lu"
  29   cpu_frequency         "state=%lu cpu_id=%lu"
  30   cpu_frequency_limits  "min=%lu max=%lu cpu_id=%lu"
  31
  32 A suspend event is used to indicate the system going in and out of the
  33 suspend mode:
  34 ::
  35
  36   machine_suspend               "state=%lu"
  37
  38
  39 Note: the value of '-1' or '4294967295' for state means an exit from the current state,
  40 i.e. trace_cpu_idle(4, smp_processor_id()) means that the system
  41 enters the idle state 4, while trace_cpu_idle(PWR_EVENT_EXIT, smp_processor_id())
  42 means that the system exits the previous idle state.
  43
  44 The event which has 'state=4294967295' in the trace is very important to the user
  45 space tools which are using it to detect the end of the current state, and so to
  46 correctly draw the states diagrams and to calculate accurate statistics etc.
  47
  48 2. Clocks events
  49 ================
  50 The clock events are used for clock enable/disable and for
  51 clock rate change.
  52 ::
  53
  54   clock_enable          "%s state=%lu cpu_id=%lu"
  55   clock_disable         "%s state=%lu cpu_id=%lu"
  56   clock_set_rate                "%s state=%lu cpu_id=%lu"
  57
  58 The first parameter gives the clock name (e.g. "gpio1_iclk").
  59 The second parameter is '1' for enable, '0' for disable, the target
  60 clock rate for set_rate.
  61
  62 3. Power domains events
  63 =======================
  64 The power domain events are used for power domains transitions
  65 ::
  66
  67   power_domain_target   "%s state=%lu cpu_id=%lu"
  68
  69 The first parameter gives the power domain name (e.g. "mpu_pwrdm").
  70 The second parameter is the power domain target state.
  71
  72 4. PM QoS events
  73 ================
  74 The PM QoS events are used for QoS add/update/remove request and for
  75 target/flags update.
  76 ::
  77
  78   pm_qos_add_request                 "pm_qos_class=%s value=%d"
  79   pm_qos_update_request              "pm_qos_class=%s value=%d"
  80   pm_qos_remove_request              "pm_qos_class=%s value=%d"
  81   pm_qos_update_request_timeout      "pm_qos_class=%s value=%d, timeout_us=%ld"
  82
  83 The first parameter gives the QoS class name (e.g. "CPU_DMA_LATENCY").
  84 The second parameter is value to be added/updated/removed.
  85 The third parameter is timeout value in usec.
  86 ::
  87
  88   pm_qos_update_target               "action=%s prev_value=%d curr_value=%d"
  89   pm_qos_update_flags                "action=%s prev_value=0x%x curr_value=0x%x"
  90
  91 The first parameter gives the QoS action name (e.g. "ADD_REQ").
  92 The second parameter is the previous QoS value.
  93 The third parameter is the current QoS value to update.
  94
  95 And, there are also events used for device PM QoS add/update/remove request.
  96 ::
  97
  98   dev_pm_qos_add_request             "device=%s type=%s new_value=%d"
  99   dev_pm_qos_update_request          "device=%s type=%s new_value=%d"
 100   dev_pm_qos_remove_request          "device=%s type=%s new_value=%d"
 101
 102 The first parameter gives the device name which tries to add/update/remove
 103 QoS requests.
 104 The second parameter gives the request type (e.g. "DEV_PM_QOS_RESUME_LATENCY").
 105 The third parameter is value to be added/updated/removed.